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Introduction 


Ahead of the release of the 2007 Microsoft Office system, Microsoft Corporation has fre¬ 
quently referred to what it calls the “new world of work”—a business environment and econ¬ 
omy characterized by mobility; a worldwide network of customers, partners, and suppliers; 
new compliance and regulatory requirements; and a need for broad visibility into business 
processes and the information that supports and governs them. Together, factors such as 
these drive the need for organizations to integrate business applications, documents, and 
workflows and transform the content of documents into business information they can act 
on. These factors make plain the essential link between knowledge workers, business informa¬ 
tion, business processes, and software. 

The 2007 Office system has much that’s new, including the Office XML file formats, an ability 
to more easily link to back-end data systems, and a new user interface. Each of these features 
provides opportunities for developers to extend Office applications. For example, the support 
of XML throughout the 2007 Office system provides a means to define information work- 
flows and document management capabilities. An organization’s IT staff can integrate systems 
such as SAP, Siebel, or Microsoft Dynamics with Office applications so that workers can per¬ 
form operations such as invoicing or ordering when working in Office rather than the back¬ 
end system itself. 

Seven Development Projects for Microsoft Office SharePoint Server 2007 and Windows SharePoint 
Services Version 3.0 focuses on another, just as critical, element of Office development— 
Microsoft Windows SharePoint Services and Microsoft Office SharePoint Server 2007, plat¬ 
forms that developers can use to create collaboration applications as well as applications and 
features that support business intelligence, workflow, data calculation, team workspaces, 
document life cycle management, content management, knowledge discovery, and project 
management. 

Information workers use an array of tools and devices to perform their jobs and collaborate 
with others: e-mail, desktop applications, mobile devices, Web browsers, Web conferencing, 
portals, and specialized line-of-business applications. Individual workers, project teams, and 
departments all need the capabilities provided by collaborative workspaces and the ability to 
archive and access information as projects are completed and new ones begin. Windows 
SharePoint Services, an integrated part of the Microsoft Windows Server 2003 operating sys¬ 
tem, provides services that enable teams and developers to build such workspaces. Windows 
SharePoint Services 3.0 can be tightly integrated with the 2007 Office system, further 
enabling information workers to make use of workspaces for organizing meetings, managing 
projects, authoring documents, and other activities that they frequently manage from tradi¬ 
tional Office applications. Windows SharePoint Services 3.0 can also be integrated with line- 
of-business applications, providing access to data that workers need to update and analyze. 
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Office SharePoint Server 2007 builds on the Windows SharePoint Services framework and 
provides services such as search in portal sites, team sites, and content management sites; user 
profiles and audience targeting; and single sign-on to facilitate integration with enterprise data 
systems. Office SharePoint Server 2007 also introduces the Business Data Catalog, which 
enables integration between enterprise portal and line-of-business applications; new docu¬ 
ment management capabilities; Web content management, which provides tools for site 
branding, creating multilingual sites, and building content deployment solutions; Microsoft 
Office SharePoint Server 2007 Excel Services, a technology for viewing, calculating, and 
extracting values from a workbook through a Web browser or through a Web service; and 
Microsoft Office Forms Server 2007, which lets information workers use a Web browser to 
interact with form templates designed with Microsoft Office InfoPath 2007. 

The last seven chapters of this book describe some basic and straightforward examples of the 
functionality and capabilities that can be included in a solution developed for Windows 
SharePoint Services, Office SharePoint Server 2007, and the 2007 Microsoft Office system. 
These examples often show sample code, but be aware that the examples were developed and 
tested only on the beta 1 build of the 2007 Office system. You’ll see a Web Part that displays 
data from a SharePoint list, for example, as well as a Web application that uses formulas in an 
Excel worksheet to perform calculations, a document approval workflow, and more. The 
examples are meant to show off core features and concepts and to help generate ideas for solu¬ 
tions that can be developed or deployed in your own organization. 

Solution Showcase for the Office System 

Developers, development managers, and organizational decision makers can consult the 
Solution Showcase for the Office System at http://www.microsojt.com/ojjice/showcase , to find 
examples, evidence, and information about ways that organizations are transforming their 
businesses and solving business problems by implementing Microsoft Office solutions. The 
Solution Showcase includes information about business scenarios and solutions for a number 
of industries, including manufacturing, financial services, public sector and government agen¬ 
cies, retail operations, health care, and professional services. 

Working with partners and customers, the Solution Showcase team identifies high-impact 
business scenarios that can be addressed with the Office System. The Solution Showcase pro¬ 
vides information and demonstrations that document the technical and business value of 
Office solutions related to these scenarios and that help facilitate discussions with business 
leaders. Solutions developed by Microsoft technology partners are shown alongside the busi¬ 
ness scenarios. 

In preparing for the release of the 2007 Office system, Microsoft worked with partners and 
customers to train and prepare them to develop solutions based on the 2007 Office system. 
To illustrate what you will soon see in the marketplace and the types of solutions developers 
will have a hand in building, the following sections describe examples of solutions that some 
of Microsoft’s technology partners currently have under way. 
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Accruent 

Accruent’s Store Lifecycle Management (SLM) product is a suite of applications that is built 
on the .NET 2.0 Framework and uses Web Parts in its portal interface. The applications 
address the full spectrum of real estate activities: market planning, site selection, design and 
construction, lease administration, and facilities management. SLM consolidates department- 
based, manual processes into a single automated process for real estate operations. For exam¬ 
ple, SLM uses a location-centric data model to merge multiple versions of real estate informa¬ 
tion into a single, unified repository. SLM’s financial engine can then analyze real estate 
performance to identify expense leakage and resource inefficiencies. Companies can execute 
store construction and remodel projects more quickly using program management templates, 
workflows, alerts, and scheduling capabilities to facilitate collaboration. Finally, controls are 
automatically instituted by a compliance system to monitor Sarbanes-Oxley compliance and 
generate accurate Financial Accounting Standards Boards (FASB) reports. 

The functionality in Accruent’s Desktop Connector offers connectivity to 2007 Office system 
applications such as Microsoft Office Outlook 2007, Microsoft Office Excel 2007, and 
Microsoft Office Word 2007. This connectivity integrates information from SLM applications 
with these commonly used programs, providing a natural flow of information and interaction 
to users where they need it. These applications help optimize the effect that real estate loca¬ 
tions—stores, restaurants, and bank branches, for example—have on company performance by 
increasing revenue days and same-store sales, reducing occupancy and construction costs, 
achieving Sarbanes-Oxley compliance, and producing accurate FASB reports. 

Figures 1 and 2 show examples of data integration between SLM and Office 2007 applications. 



Figure 1 Integration with an Office Outlook 2007 task item. (© 2006 Accruent, Inc. All rights 
reserved.) 
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Figure 2 A customized task pane in Office Word 2007. (© 2006 Accruent, Inc. All rights reserved.) 


AVIVA Consulting Group 

The AVIVA Compliance Environment (ACE • S) is a solution for document management, pro¬ 
cess control, and executive visibility for Sarbanes-Oxley Section 302 and 404 compliance. The 
solution is based on a Web portal that uses Microsoft technologies to organize and manage 
internal control documentation in addition to evaluation and testing documents and results. 
ACE • S can be utilized by all designated professionals, including internal and external partic¬ 
ipants, so that all phases of a compliance program can be managed comprehensively. The 
solution is built on Windows SharePoint Services and its capabilities provided by products 
and technologies such as Microsoft Office InfoPath, ASP.NET 2.0, Microsoft SQL Server 2005 
Reporting Services, Microsoft Information Bridge Framework 1.5, Office Word 2007, Office 
Excel 2007, and AVIVA Narrative Composer 2.1. 

The solution’s components provide a structured control framework that is based on COSO 
and the latest Public Company Accounting Oversight Board (PCAOB) recommendations and 
nomenclature. An organization can configure its own relationships between processes, con¬ 
trol objectives, risks, controls, and so on, and use its own nomenclature if needed. In addition, 
through AVIVA’s Narrative Composer, a Microsoft Word plug-in that provides a direct link 
from a document to a portal environment, the solution supports the creation of walkthrough 
documentation that provides context for each of the controls. 
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ACE • S manages the review process by ensuring that process owners periodically review inter¬ 
nal control documentation for accuracy and completeness. The solution also provides an 
audit trail of all reviews and the date the review was performed. AVIVA uses SourceCode 
K2.net for advanced workflow capabilities that include the ability to ensure that policies and 
procedures conform to an organization’s specifications. 

Each user’s main Web portal view is based on his or her role and contains lists of tasks, mon¬ 
itoring of relevant processes, and reports. ACE • S provides a comprehensive list of configured 
reports that provide visibility into the status of the compliance effort, including the Internal 
Control Matrix, the Deficiency Matrix, Assertion Coverage, and the Executive Summary. 

Each report is intended for a specific type of user, and users can create a subscription that 
automatically delivers critical reports at a specified interval. 

Figure 3 shows a sample of the Executive Summary report. Figure 4 on the next page shows 
a Control Activity page. 



Figure 3 The Executive Summary report 
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Figure 4 A Control Activity page used for managing compliance requirements 


CorasWorks 

CorasWorks is developing a solution named Workplace Suite for Office SharePoint Server 
2007. The solution enables organizations to design, create, and manage a collaborative work¬ 
place of interconnected business applications without the time and expense of custom pro¬ 
gramming. The solution includes 40 business solutions that can be used as is or that can be 
easily extended to meet specific needs. For example, the Project Management solution can be 
configured for multiple small projects or a large project or to support an integrated, world¬ 
wide program management office. 

Workplace Suite for Office SharePoint Server 2007 includes a set of “intelligent” modular com¬ 
ponents that can be snapped together to create flexible business applications and that inte¬ 
grate applications to create a complete workplace. The suite also includes the Workplace 
Configuration Manager, which is used to manage and control the behavior of the components, 
applications, interconnected solutions, and the workplace, including the integration of exter¬ 
nal data sources. In addition, the suite provides pre-built integration of Office SharePoint 
Server 2007 capabilities, including workflows, Office Forms Server 2007, enterprise content 
management, and the Business Data Catalog. Figure 5 shows an example of a workspace and 
the types of operations users can perform. 
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Figure 5 A status dashboard that's part of the Workplace Suite for Office SharePoint Server 2007 

KnowledgeLake 

KnowledgeLake extends the capabilities of Windows SharePoint Services as the core reposi¬ 
tory for an enterprise content management (ECM) solution. KnowledgeLake’s ECM solution 
provides capture, imaging, and content-centric workflow that allow companies to manage mil¬ 
lions of paper-based documents and unstructured information and streamline business work- 
flow processes. 

KnowledgeLake Capture is a production-level scanning solution, usually found in mailrooms, 
that allows users to scan, index, and export documents within a single user interface. 
KnowledgeLake Capture automatically exports images and indexing data to the SharePoint 
repository, where it queries SharePoint for the available libraries and content types. 
KnowledgeLake Capture is integrated with KnowledgeLake Imaging and features bar code 
and patch code recognition, image enhancement, and index validation. Lor the 2007 Office 
system release, KnowledgeLake Capture enables users to select content types directly from 
the Indexing screen and use optical character recognition (OCR) to apply metadata proper¬ 
ties before saving scanned documents to a SharePoint site. 

KnowledgeLake Imaging enhances the capabilities of SharePoint to enable easy organization, 
storage, and access of all unstructured business documents (paper, faxes, e-mail, computer 
reports, and so on). An integrated Web Part within the SharePoint interface allows users to 
search for documents by index values that are created and maintained as a SharePoint site 
feature. Users can even configure the search results by document type, date, or any other 
column. 

The thin-client viewer allows users to view scanned documents from SharePoint using 
thumbnails, zooming, and rotating, with a user interface usually seen only in Windows Lorms 
applications. This feature is made possible through AJAX technologies by allowing partial 
page postbacks. Users can also add annotations to the documents and save them back to 
SharePoint with the markup. Annotations, drawn completely on the client side using 
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JavaScript, include highlights, rectangles, text, stamps, straight lines, freehand lines, and 
sticky notes. Figures 6 and 7 show examples from the KnowledgeLake ECM solution. 



Figure 6 After a user clicks Accept, the image is uploaded to a SharePoint site. C#, SharePoint Web 
services, and the Frontpage Remote Procedure Call protocol allow this operation to occur. 



Figure 7 Once the search results are returned, the site feature adds an icon to view any image via 
KnowledgeLake Imaging's thin-client viewer (contains no ActiveX or Java). 


SharePoint integration built into the viewer makes KnowledgeLake Imaging look and feel like 
an Office 2007 client application. Users can view and modify SharePoint properties (the 
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metadata added with KnowledgeLake Capture), as well as check the status and act on associ¬ 
ated Office workflow items. Figure 8 shows the KnowledgeLake AJAX viewer. 



Figure 8 KnowledgeLake AJAX Image Viewer 

Metalogix Software 

Metalogix’s Migration Manager is a content migration solution that enables users to discover, 
analyze, extract, and transform content from Web sites, file shares, existing SharePoint repos¬ 
itories, Microsoft Content Management Server 2002, and third-party enterprise content 
management systems. Information from these sources can be exported to SharePoint libraries 
and lists. 

Migration Manager includes crawlers for discovering content on the file system or any HTTP- 
accessible Web site. These crawlers are compatible with enterprise content management 
systems such as Vignette, Interwoven, IBM, Tridion, Stellent, and Microsoft Content Man¬ 
agement Server 2002. Static sites are also supported in addition to many other third-party 
systems. Migration Manager also helps organizations analyze content assets by providing a 
metadata explorer and filtering tools. Users can determine what type of content exists 
(.html, .doc, .pdf, or other file formats), when it was created, how frequently it is accessed and 
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modified, and who authored it. Migration Manager lets users add metadata of any data type to 
multiple content items at the same time. After the metadata is defined, it can be easily mapped 
to SharePoint library columns. Web content, documents, and metadata can be exported to 
any Office SharePoint Server 2007 site that is accessible through HTTP. Content in HTML or 
XML format can be mapped to Office SharePoint Server page fields or to Web Part pages, and 
metadata can be mapped to existing columns or new columns can be created automatically. 

Figures 9, 10, and 11 illustrate operations of Migration Manager. 
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Figure 9 The main application window for Migration Manager. A row is added to the List View for 
each content item added. The Property sheet lets users view and edit metadata associated with a 
particular content item. The Property Explorer filters and organizes the list. 
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from within an HTML or XML document. 
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Figure 11 This split view enables users to view source content in the upper pane and exported con¬ 
tent in the lower pane. This example shows an HTML page above a newly created page in an Office 
SharePoint Server 2007 pages library. 


OSISoft 

OSISoft has defined an Excel Services solution that includes a set of user-defined functions 
that retrieve time-series data from a proprietary database. The functions are defined for an 
Excel workbook, which can be rendered in a browser using Excel Web Access. By defining 
cells that act as parameters, a user can change the value of a cell when the workbook is ren¬ 
dered in the browser, and the solution can retrieve the data for any time period. For example, 
if one of the user-defined functions displayed an irregular trend in the data being analyzed, 
users could focus on that time period to find out the cause of the irregularity. 

Figure 12 shows the workbook rendered in Excel Web Access with a new value in the Param¬ 
eters list. Figure 13 shows the workbook in the browser with the updated data. 
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Quilogy 

Quilogy performed a proof of concept using the 2007 Office system for a large energy client. 
The customer had an inefficient paper and document-based process for bringing on contract 
staff. Quilogy and Microsoft helped them envision a new process that leverages the 2007 
Office system. Office InfoPath 2007 forms, routed through an Office SharePoint Server 2007 
workflow, automate the contractor on-boarding process—providing new speed, control, and 
accountability to this process. Office Word 2007 documents, such as the Contractor Back¬ 
ground Investigation form, can be securely incorporated into the workflow process using 
Rights Management Services to provide strict control over document information. Workflow 
tasks can arrive in an Office Outlook 2007 e-mail message, show up on the Office Outlook 
2007 To-Do Bar, and be completed offline. Managers can use Office Excel 2007 to produce 
visualizations of the workflow process and its metrics to easily identify bottlenecks and 
throughput. 

Figure 14 shows the workflow process on a SharePoint site. Figure 15 shows an Office 
InfoPath 2007 form template rendered in Internet Explorer. 



Figure 14 A workflow process on a SharePoint site 
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Figure 15 An Office InfoPath 2007 form template rendered in Internet Explorer 


Resolute 

Resolute has been working with Microsoft on solutions that integrate Microsoft Office Groove 
and Windows SharePoint Services. Some of this integration can be implemented out of the 
box. Groove and Windows SharePoint Services work together in a variety of common scenar¬ 
ios; for example, creating a workspace that can be used by a mobile sales force to build and 
review sales proposals, sharing internal content on a SharePoint site with users outside an 
organization, or archiving content stored in Groove workspaces to a SharePoint document 
library. 

Another aspect of these solutions uses the Groove forms tool to perform integration with 
SharePoint lists on an existing site. The integration makes use of SharePoint Web services pro¬ 
vided by the Groove client and the Groove Enterprise Data Bridge (EDB). Synchronization 
occurs by copying items from SharePoint lists into the forms tool list, and from the forms tool 
list into a SharePoint list. Because the Web services required for this component are available 
in both the Groove client and EDB, the solution works in both environments. 

In the client environment, users must install a synchronization tool to perform the synchroni¬ 
zation; however, only workspace members who will perform the synchronization are required 
to have the synchronization tool. In a server environment, where the server is running the 
EDB, a simple API exposed by the application permits server application developers to config¬ 
ure and control this synchronization process. The synchronization application can run as a 
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Windows service. To configure the server version of the application, a small Web application 
is provided that permits users to select workspaces and tools to synchronize. This application 
runs on the server that also hosts the EDB and will list each workspace that the EDB instance 
is a member of, along with all of the forms tools contained within these workspaces. 

Another aspect of integrating Groove workspaces and SharePoint sites is a solution for provi¬ 
sioning Groove workspaces from SharePoint sites from both EDB and a Groove client add-in. 
In the solution, users will see a button on Groove-enabled SharePoint sites. This button is 
installed as part of a SharePoint site feature. When a user clicks this button, the user will be 
sent a workspace invitation. On accepting the invitation, the user will find a workspace with 
SharePoint Files Tools for the various document libraries on the site already set up. 

Depending on which version is installed (client or server), the button will run code to launch 
the provisioning process on the user’s computer or code to launch the provisioning process 
on the server. SharePoint site administrators can selectively enable the provisioning feature on 
individual sites or even on an entire farm. In the provisioning process, a workspace is created 
on the Groove client or on the EDB server. Next, SharePoint Files Tools are created for each 
document library on the SharePoint site, and synchronization options for these tools are set 
up. Finally, the list of site members from the SharePoint site is read, and each user with Con¬ 
tributor or a higher-level access is invited into the workspace. In the client version of this solu¬ 
tion, the user who created the workspace will already be a member and will not need to be 
invited into the space. In the server version, the EDB server will remain a member of the work¬ 
space. After the Groove workspace has been provisioned, users can use the workspace with¬ 
out any additional software. Groove’s SharePoint Files Tools will automatically handle 
synchronization without any additional intervention. Beyond simple usage, however, the 
server version of this scenario presents a compelling starting point for integration with other 
enterprise applications, or even other data held in SharePoint itself. 

Figures 16 and 17 show a Groove form before synchronization and a SharePoint list after the 
form and the site have been synchronized. 
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Figure 16 A Groove form before synchronization 



Figure 17 A SharePoint list after the Groove form and the list have been synchronized 
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3Sharp 

3Sharp is developing a building permit application solution that uses Office InfoPath 2007, 
Forms Services, Excel Services, Windows SharePoint Services, and a workflow designed using 
Microsoft Office SharePoint Designer 2007. The 3Sharp solution is designed for municipali¬ 
ties that need an electronic process for building permit applications submitted by residents 
and business owners. This process requires that users have access to a public site to complete 
a building permit application form, which captures specific data about a building project. The 
process also requires a moderately complex workflow that executes based on the data submit¬ 
ted. The solution is designed for Office 2007 clients and servers, all with no code. 

The core of the solution is an Office InfoPath 2007 form, which was designed once and 
deployed for access both through the Office InfoPath 2007 client and through a Web browser. 
To apply for a building permit, customers simply click a link on the city’s public Web site and 
the browser-based form opens. Customers enter data in the form, including project informa¬ 
tion. The form is able to retrieve property data from a back-end system and is also able to 
retrieve a Permit Amount value using Excel Services. (The form sends customer-supplied 
information to a published Excel workbook and retrieves a resulting calculated value.) When 
the customer submits the form, it is routed to an internal SharePoint forms library. A custom 
SharePoint Designer-based workflow automatically notifies a clerk, who ensures that a design 
drawing has already been submitted, and then assigns a compliance reviewer for the project. 
The compliance reviewer receives a workflow e-mail message with a generated hyperlink to 
the actual form and reviews the form to determine whether the project meets certain require¬ 
ments (for example, fire safety regulations) before submitting the form back to the forms 
library. If all requirements have been met, a workflow e-mail message is sent to the applicant 
indicating that the application has been approved and that the permit amount is due. Other¬ 
wise, a different e-mail message with a hyperlink to the form is sent to the applicant, who must 
then make changes and resubmit the data to start the review process again. 

Microsoft Office Developer Center 

Any developer working on an Office-based solution or application that is based on Windows 
SharePoint Services should take full advantage of the information available on the developer 
centers on MSDN, at http://msdn.microsojt.com. Developers familiar with the Microsoft Office 
Developer Center ( http://msdn.microsoft.com/ojfice ) know this site as a resource where they 
can obtain information through technical articles and documentation, sample code, labs, and 
community activities. 
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The next major release of Microsoft SharePoint Products and Technologies is scheduled for 
fall 2006. This release includes Microsoft Windows SharePoint Services 3.0 and Microsoft 
Office SharePoint Server 2007. This chapter covers what’s new for developers in Windows 
SharePoint Services 3.0. The developer-centric features of Office SharePoint Server 2007 will 
be covered in the next chapter, which builds on this one. 

Windows SharePoint Services 3.0 is a royalty-free add-on for the Windows Server 2003 
operating system. At its core, Windows SharePoint Services 3.0 plays the role of a scalable site¬ 
provisioning engine. It solves the problem of creating and managing hundreds or thousands 
of Web sites and making them accessible to tens of thousands of users. Windows SharePoint 
Services 3.0 scalability is achieved using an architecture designed with a Web farm environ¬ 
ment in mind. This architecture is based on stateless front-end Web servers that rely on 
Microsoft SQL Server in the back end for storing content and other site-related data. 

As in the previous versions, Windows SharePoint Services 3.0 supplies out-of-the-box collab¬ 
oration features that make it simple for users to create and design Web sites with things like 
shared calendars, contact lists, and document libraries. However, developers should see Win¬ 
dows SharePoint Services 3.0 as something far more powerful than a collaboration tool aimed 
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at users. Windows SharePoint Services 3.0 is a full-fledged development platform that adds a 
tremendous amount of value on top ofASP.NET. 

Windows SharePoint Services 3.0 provides value beyond the ASP.NET 2.0 development plat¬ 
form by means of a richer provider model. It facilitates provisioning and storage for pages, 
lists, and document libraries. This provisioning can be driven through custom code or 
through user actions in the browser-based user interface. Behind the scenes, Windows Share- 
Point Services 3.0 automatically works out how and where to store this content. Windows 
SharePoint Services 3.0 also eliminates many tedious tasks required in typicalASP.NET devel¬ 
opment because it additionally supplies the UI elements for users to add, view, and modify 
content. 

In this chapter, I assume you already know something about the previous version of 
Windows SharePoint Services (2.0), so I can concentrate on the most significant developer 
enhancements to this new version. For more background information you can read “Use Win¬ 
dows SharePoint Services as a Platform for Building Collaborative Applications” 

( http://msdn.microsoft. com/ msdnmag/issues/04/07/WindowsSharePointServices/). 

Also keep in mind that research and code samples for this chapter are based on the beta 1 
release of Windows SharePoint Services 3.0. It’s possible that some of the terms and code 
used in this chapter might differ in the released version. 

Integration with ASP.NET 2.0 

Windows SharePoint Services 3.0 provisioning starts at the level of the IIS Web site. Before 
you can create your first Windows SharePoint Services site, someone must run an administra¬ 
tive procedure to extend 3.0 functionality onto one or more IIS Web sites. In Windows Share- 
Point Services 2.0, the term virtual sewer was used to describe an IIS Web site that had been 
extended with Windows SharePoint Services functionality. To avoid confusion with another 
Microsoft product of the same name, the Windows SharePoint Services 3.0 documentation 
now refers to an IIS Web site extended with Windows SharePoint Services functionality as a 
Web application. 

Windows SharePoint Services 2.0 was integrated with IIS 6.0 and ASP.NET 1.1 using an ISAPI 
filter DLL. This integration technique results in IIS routing requests to Windows SharePoint 
Services before ASP.NET. This routing has proven to be problematic in certain situations 
because Windows SharePoint Services takes control of an incoming HTTP request before it 
has a chance to be properly initialized with ASP.NET context. 

The way in which Windows SharePoint Services 3.0 integrates with ASP.NET has been com¬ 
pletely redesigned. First of all, Windows SharePoint Services 3.0 is built upon ASP.NET 2.0, 
which provides significant enhancements overASP.NET 1.1. Furthermore, the integration 
between Windows SharePoint Services 3.0 and ASP.NET 2.0 was changed to route incoming 
requests through the ASP.NET runtime before Windows SharePoint Services. The Windows 
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SharePoint Services team achieved these improvements to the routing infrastructure by 
removing the ISAPI filter and adding an HttpModule and an HttpHandler that are registered 
with ASP.NET using standard Web.config entries. This means incoming HTTP requests 
always enter the ASP.NET run-time environment and are fully initialized with ASP.NET con¬ 
text before they are forwarded to the code written by the Windows SharePoint Services team 
to carry out Windows SharePoint Services-specific processing. 

Also note that when you extend an IIS Web site to become a Windows SharePoint Services 
Web application, Windows SharePoint Services 3.0 adds a wildcard application map to the IIS 
metabase. This wildcard application map serves to route all incoming HTTP requests to the 
ASP.NET runtime regardless of their extension. This wildcard application map is necessary to 
forward a request for any type of file (for example, .pdf, .doc, .docx) to ASP.NET, which then 
forwards the request to Windows SharePoint Services for processing. 

Another relevant issue of the new architecture has to do with how .aspx pages are parsed and 
compiled. The .aspx page parserusedbyASP.NET 1.1 works only with .aspx pages that reside 
on the local file system. However, Windows SharePoint Services architecture relies on storing 
.aspx pages inside a SQL Server database. Since Windows SharePoint Services 2.0 relies on 
ASP.NET 1.1, the Windows SharePoint Services team had to create their own .aspx page 
parser. Unfortunately, the .aspx parser of Windows SharePoint Services 2.0 does not support 
many of the richer features offered by the ASP.NET .aspx page parser. 

ASP.NET 2.0 introduced a new pluggable component type known as a virtual path provider. 
A developer can write a custom component that retrieves .aspx pages for any location includ¬ 
ing a database such as SQL Server. Once a custom virtual path provider retrieves an .aspx 
page, it can then hand it off to ASP.NET to conduct the required parsing and compilation. 
ASP.NET also gives the virtual path provider a good deal of control as to how .aspx pages are 
parsed and whether they are compiled or run in a non-compile mode. 

The Windows SharePoint Services 3.0 team has created their own virtual path provider 
named SPVirtualPathProvider, which is shown in Figure 1-1 on the next page. As you can see, 
the SPVirtualPathProvider is able to retrieve .aspx pages from SQL Server and then hand them 
off to the .aspx page parser supplied byASP.NET 2.0. That means the Windows SharePoint 
Services 3.0 team was not required to evolve their .aspx page parser from the previous ver¬ 
sion. It also means that Windows SharePoint Services 3.0 does not suffer from a reduced fea¬ 
ture set with respect to page parsing as it does with Windows SharePoint Services 2.0. 

If you’re familiar with the architecture of Windows SharePoint Services 2.0, you’ve probably 
heard the terms “ghosting” and “unghosting” used in conjunction with the .aspx pages of a 
Windows SharePoint Services 2.0 site. Page ghosting is a Windows SharePoint Services fea¬ 
ture that allows a front-end Web server to store an .aspx page template on its local file system 
and to share that page template across many different sites. Page ghosting offers performance 
benefits because Windows SharePoint Services can serve up pages for thousands of sites 
using a page template stored on the local file system and loaded into memory a single time. 
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Figure 1-1 Windows SharePoint Services employs a custom virtual path provider to employ the 
.aspx page parser supplied by ASP.NET 2.0. 


Windows SharePoint Services 2.0 supports user modifications to the page template using 
tools such as Microsoft Office FrontPage 2003. Once a user modifies a page template and 
saves the changes, a customized version of the page is stored on SQL Server for that particular 
site. In Windows SharePoint Services 2.0, this is often referred to as unghosting a page. 


Windows SharePoint Services 3.0 still supports page templates that live on the Web server as 
well as customized versions of those page templates that are stored on SQL Server. Fiowever, 
the Windows SharePoint Services team and their documentation have stopped using the 
terms ghosting and unghosting because they do not translate well into other spoken lan¬ 
guages. In Windows SharePoint Services 3.0, the term “uncustomized page” refers to a page 
template used directly from the local file system of the Web server, and the term “customized 
page” refers to a modified version of the page template that has been written to the content 
database for a particular site. 


Another change to be aware of is that Microsoft Office FrontPage 2003 has been renamed in 
its new release as Microsoft Office SharePoint Designer 2007. Like the previous versions of 
FrontPage, Office SharePoint Designer 2007 is targeted more toward users than developers. 
However, it’s nonetheless a handy tool to have in your bag of tricks as a Windows SharePoint 
Services developer. 


Office SharePoint Designer 2007 provides a code editor and WYSIWYG designer for custom¬ 
izing .aspx pages within Windows SharePoint Services 3.0 sites. You can also create new 
pages within a Windows SharePoint Services site that have no corresponding page template 
on the Web server. Office SharePoint Designer 2007 supports creating lists and document 
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libraries and even supplies a new wizard for creating custom workflows on a Windows Share- 
Point Services site. Workflows in Windows SharePoint Services 3.0 will be discussed in more 
depth later in this chapter. 

Working with Master Pages 

One of the most tedious aspects of customizing and branding sites in Windows SharePoint 
Services 2.0 is creating a consistent look and feel across pages. This is because ASP.NET 1.1 
does not provide any suitable page templating technique that can be used across the pages 
within a Windows SharePoint Services 2.0 site. As a result, many developers and designers 
have resorted to copying and pasting HTML layouts from page to page. As you can imagine, 
this makes it very hard to customize and maintain a site whose layout requirements differ 
from the out-of-the box experience with a standard Windows SharePoint Services 2.0 site. 

As you’re probably aware, ASP.NET 2.0 has introduced a powerful page templating feature 
known as master pages. A master page is a template that allows you to define a standard page 
layout for an entire site with elements such as a banner, navigation controls, and menus. The 
pages that link to a master page are known as content pages. 

The key concept is that each content page links to the master page to get the shared layout, 
and then extends the master page by adding customized content to replaceable named 
placeholders. For more information about how master pages work in ASP.NET, read 
“Master Your Site Design with Visual Inheritance and Page Templates” 

( http://msdn.microsoft. com/msdnmag/issues/04/06/ASPNET20MasterPages/default.aspx). 

Windows SharePoint Services 3.0 was designed from the ground up to embrace the master 
page infrastructure of ASP.NET 2.0. Every Windows SharePoint Services 3.0 site is provi¬ 
sioned with a special catalog known as the Master Page Gallery containing a master page 
named default.master. This master page defines a common layout for every site’s home page 
(Default.aspx) as well as all the standard Windows SharePoint Services form pages associated 
with lists and document libraries (for example, Allltems.aspx, Newltem.aspx). The master 
page layout includes standard Windows SharePoint Services menus and navigation controls. 
An example of a page based on the standard layout defined by default.master is shown in 
Figure 1-2 on the next page. 

The definition of default.master includes several different named placeholders such as Place- 
HolderPageTitle , PlaceHolderMain , and PlaceHolderLejtNavigation. This makes it relatively sim¬ 
ple to create a new custom content page that has the same layout as the other pages in a site. 
Take a look at the simplicity of the content page definition shown in the following code. 

<%@ Page ianguage="C#" MasterPageFile="~masterurl/default.master" %> 

<asp:Content ContentPiaceHoiderld="PiaceHoiderMain" runat="server"> 

<h3>weicome to customization with WSS v3</h3> 

This is so much easier than it was in WSS v2! 

</asp:Content> 



6 


7 Development Projects for Microsoft Office SharePoint Server 2007 and Windows SharePoint Services 



Figure 1-2 The standard layout of pages within a Windows SharePoint Services site is controlled 
through default.master. 

The content page definition shown in the code could not be any simpler. It does nothing other 
than add a minimal fragment of HTML content inside PlaceHolderMain. However, it produces 
the standard Windows SharePoint Services page layout with site icons, menus, and navigation 
bars, as shown in Figure 1-3. Once you learn how to use the standard set of placeholders 
defined in default.master, you can easily swap out standard Windows SharePoint Services ele¬ 
ments like menus and navigation bars and replace them with your own ASP.NET controls and 
Web Parts. This can be done for pages at the scope of a site, a site collection, or even on a farm¬ 
wide basis. 

Master pages and content pages are stored and loaded using the same concepts of page 
templates and page customization discussed earlier. There are page templates defined for the 
master page as well as for content pages that reside on the local file system of the front-end 
Web server. Each site initially uses an uncustomized (that is, ghosted) version of the master 
page template and content page templates. However, once a user customizes and saves one of 
these pages for a particular site using a tool such as Office SharePoint Designer 2007, a cus¬ 
tomized (unghosted) version is saved in the SQL Server database. 

It’s possible to customize the master page for a site while leaving the content pages uncus¬ 
tomized. Likewise, it’s possible to customize one or more content pages while leaving the 
master page uncustomized. Furthermore, if you customize either the master page or a content 
page and later wish to undo your changes, both the browser-based UI of Windows SharePoint 
Services 3.0 and Office SharePoint Designer 2007 provide simple menu commands to discard 
customization changes from the SQL database and revert back to the original page template. 
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Figure 1-3 It's easy to create custom content pages that use the standard Windows SharePoint 
Services layout. 

You might have noticed in the code on page 5 that the content page shown in Figure 1-3 links 
to the master page using a special syntax in the form of -masterurl/default.master. This is a 
tokenized reference to a master page that can be changed programmatically on a site-wide 
basis. You can accomplish this by acquiring an SPWeb reference to the current site and then 
updating the MasterUrl property. 

using System.windows.Forms; 
using Microsoft.SharePoint; 

namespace MyHandypageCustomizer { 

public partial class frmMain : Form { 

void cmdSetMasterurl_Click(object sender, EventArgs e) { 

SPSite SiteCollection = new SPSite(@"http://localhost"); 

SPWeb TopLevelsite = SiteCollection.OpenwebO; 

TopLevelSite.Masterurl = txtMasterurl.Text; 

TopLevelsite.updateO ; 

} 

} 

} 

Note that each site has its own Master Page Gallery with a default.master and its own Master- 
Url property. That means all the sites in a site collection do not automatically use the same 
master. However, with the use of recursion it’s pretty easy to write some code against the Win¬ 
dows SharePoint Services 3.0 object model to synchronize a top-level site and all the child 
sites in a site collection to use the same master pages. 

void cmdSynchronizeChildren_Click(object sender, EventArgs e) { 

SPSite SiteCollection = new SPSite(@"http://localhost"); 

SPWeb TopLevelsite = SiteCollection.OpenwebO; 
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updateMasterurlRecursive(Topl_evelSite, txtMasterur) .Text) ; 

} 

void updateMasteruriRecursivefSPWeb site, string uri) { 
site.Masteruri = uri; 
site.updateO; 

foreach (SPWeb child in site.webs) { 

UpdateMasterurlRecursive(child, uri); 

} 

} 

In addition to -masterurl/default.master, there is another dynamic token for master pages in 
the form of -masterurl/custom.master. This dynamic token works in conjunction with the 
CustomMasterUrl property of a site and provides a secondary target master page that can be 
redirected programmatically. There are also two static master page tokens that start with 
either -site or -sitecollection. These static tokens allow you to hard-code a relative path to a 
master page from either the root of the current site or the root of the current site collection. 

Web Parts in Windows SharePoint Services 3.0 

One of the most popular ways for developers to extend Windows SharePoint Services 2.0 
sites has been to create custom Web Parts. Web Parts are great because they add the extra 
dimensions of user customization and personalization. As a consequence, many teams at 
Microsoft and third-party companies alike have built custom Windows SharePoint Services 
2.0 solutions using Web Parts. 

Because of the popularity of Web Parts in Windows SharePoint Services 2.0, Microsoft 
decided to add support for custom Web Part development to ASP.NET 2.0. This strategy to 
reach a wider audience of developers was accomplished by creating a new Web Part infra¬ 
structure for ASP.NET 2.0 that is similar yet distinct from the Web Part infrastructure created 
for Windows SharePoint Services 2.0. 

Consequently, there are now two different styles of Web Parts. The older WSS-style Web 
Parts depend on Microsoft.SharePoint.dll and must inherit from the WebPart base class 
defined by the Windows SharePoint Services 2.0 teams in the Microsoft.SharePoint.Web- 
PartPages namespace. The newer ASP-style Web Parts depend on System.Web.dll and must 
inherit from a different base class also named WebPart defined by theASP.NET 2.0 team in the 
System.Web.Ul.WebControls.WebParts namespace. 

It is an important design goal for Windows SharePoint Services 3.0 to run both the older 
WSS-style Web Parts as well as the newer ASP-style Web Parts. This has been accomplished 
by building the Windows SharePoint Services 3.0 support for Web Parts on top of the 
ASP.NET Web Part infrastructure, and then making changes to Microsoft.SharePoint.dll so 
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that WSS-style Web Parts written for the Windows SharePoint Services 2.0 environment 
would be forwardly compatible with the Windows SharePoint Services 3.0 run-time 
environment. 

To explain how Web Parts are loaded and run in Windows SharePoint Services 3.0, this sec¬ 
tion discusses how the Windows SharePoint Services 3.0 architecture was redesigned to layer 
on top of the ASP.NET 2.0 Web Part infrastructure. First, I will cover how Web Part Pages are 
laid out in Windows SharePoint Services 3.0, and then I get into the details of how to develop 
custom Web Parts for a Windows SharePoint Services 3.0 environment. 

To run Web Parts in an ASP.NET 2.0 application, you must create an .aspx page that contains 
exactly one instance of the WebPartManager control and one or more WebPartZone controls. 
The WebPartManager control is responsible for serializing Web Part-related data as well as 
storing and retrieving it from the tables in the ASP.NET services database. 

The .aspx page serving as a Web Part Page can also contain Editor Parts, which allow users 
to customize and personalize persistent Web Part properties. Web Part Pages can also 
contain Catalog Parts, which allow users to add new Web Parts to zones. To acquire 
more background about how the ASP.NET 2.0 Web Part infrastructure works, read 
“ASP.NET 2.0: Personalize Your Portal with User Controls and Custom Web Parts” 

( http://msdn.microsoft. com/msdnmag/issues/05/09/WebParts/). 

The Web Part infrastructure of Windows SharePoint Services 3.0 is built on a control named 
SPWebPartManager that is derived from the ASP.NET 2.0 WebPartManager control. The 
SPWebPartManager control overrides the standard behavior of the WebPartManager control to 
persist Web Part data inside the Windows SharePoint Services content database instead of the 
ASP.NET services database. In most cases, you don’t have to worry about dealing directly with 
the SPWebPartManager control because the one and only required instance is already defined 
in the standard default, master page. When you create a content page that inherits from 
default.master, the SPWebPartManager control is already there. 

The other controls that appear on a typical Windows SharePoint Services 3.0 Web Part Page 
are shown in Figure 1-4 on the next page and include Web Part zones, Editor Parts, and Cat¬ 
alog Parts. Note that Web Part zones for a Web Part Page in Windows SharePoint Services 3.0 
should be created using the WebPartZone control defined in the Microsoft. SharePoint. Web- 
PartPages namespace and not the standard WebPartZone control from ASP.NET 2.0. 

Instances of the WebPartZone control are usually defined in content pages. The following code 
shows a simple example of creating a content page designed to act as Web Part Page in a Win¬ 
dows SharePoint Services 3.0 site. As you can see, this .aspx file links to default.master just 
like the example you saw earlier. However, it also explicitly inherits from the WebPartPage 
base class and adds two WebPartZone controls into PlaceHolderMain. 
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Figure 1-4 A Web Part Page in Windows SharePoint Services 3.0 requires the SPWebPartManager 
control and one or more WebPartZone controls. If you create a content page that inherits from the 
WebPartPage class, you also get the benefit of Windows SharePoint Services 3.0 supplying Editor 
Parts and Catalog Parts. 

<%@ Assembly Name="[Fully-qualifi ed name for Microsoft.Sharepoint.dll]" %> 

<%@ Page ianguage="C#" MasterPageFile="~masterurl/default.master" 
inherits="Microsoft.Sharepoint.webpartPages.WebPartPage" %> 

<%@ Register Tagprefix="webPartPages" 

Namespace="Microsoft.Sharepoint.webpartpages" 

Assembiy="[Fuiiy-quaiified name for Microsoft.Sharepoint.dll]” %> 


<asp:Content ContentPiaceHolderld="PlaceHolderMain" runat="server"> 

<h3>My Custom web Part Page</h3> 

ctable border="5" cellpadding="5" cellspacing="0"> 

<tr> 

<td valign="top”> 

<webpartpages:webPartzone runat="server" lD="Left" 

Title="Left zone" /> 

</td> 

<td valign="top"> 

<webpartpages:webPartzone runat="server" lD="Right" 

Title="Right zone" /> 

</td> 

</tr> 

</table> 

</asp:Content> 

When you create a Web Part Page for a standard ASP.NET 2.0 application, you are required to 
add logic that interacts with the WebPartManager control to manage the Web Part display 
mode. Typically, you also need to explicitly add Editor Parts and Catalog Parts to the page 
along with the EITML layout to accommodate them. Fortunately, you don’t have to do these 
things when creating content pages for a Windows SharePoint Services 3.0 site. Instead, you 
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inherit from the WebPartPage class that’s defined in the Microsojt.SharePoint.WebPartPages 
namespace and let it do all this work for you behind the scenes. 

Figure 1-5 shows a screen shot of a custom Web Part Page in action. This is the display gener¬ 
ated by the custom Web Part Page definition shown in the previous code when the user has 
entered edit mode. Notice that the page allows users to add Web Parts into zones and to mod¬ 
ify existing Web Parts using standard Editor Parts. 
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Figure 1-5 Custom Web Part Pages that inherit from the WebPartPage class provide automatic 
support for managing display mode as well as providing Editor Parts and Catalog Parts. 


Developing Custom Web Parts 

The preferred approach for creating Web Parts for Windows SharePoint Services 3.0 sites is to 
create ASP-style Web Parts. At a minimum, this involves creating a class that inherits from the 
WebPart base class defined in the System.Web.Ul.WebControls.WebParts namespace and over¬ 
riding the RenderContents method. If you want to add persistent Web Part properties, you use 
the same technique that is used in ASP.NET, as shown in the following code. 

using System; 
using System.web.ui; 

using System.web.ui.webcontrols.webParts; 

namespace LitwarewebParts { 

public class SimplewebPart : WebPart { 

// backing field for caching property value 
protected string _zipCode; 

[ // persistent web Part property 
personalizableO , 
webBrowsable(true), 
webDisplayName("zip Code"), 
webDescription("used to track user zip code") 
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] 

public string zipCode { 

get{ return _zipCode; } 
set{ value = _zipCode; } 

} 

protected override void RenderContents(HtmlTextwriter writer) { 
writer.write("You live at " + _zipcode); 

} 

} 

} 

The Web Part definition shown in this code has no dependencies on Microsoft.SharePoint.dll 
so it can be used in either a standard ASP.NET application or a Windows SharePoint Services 
3.0 site. In many cases, you will want to add a reference to Microsoft.SharePoint.dll with a 
Web Part library project so the code behind your Web Parts can program against the Win¬ 
dows SharePoint Services 3.0 object model. 

In addition to supporting ASP-style Web Parts, Windows SharePoint Services 3.0 was also 
designed to support Web Parts created for the Windows SharePoint Services 2.0 environ¬ 
ment. These older WSS-style Web Parts inherit from the WebPart base class from 
Microsoft.SharePoint.dll that is defined in the Microsoft.SharePoint.WebPartPages namespace. 

The WebPart class in the Windows SharePoint Services 2.0 version of Microsoft.SharePoint.dll 
was designed to inherit from the ASP.NET Control class as shown in Figure 1-6. However, you 
can also see that the WebPart class in the Windows SharePoint Services 3.0 version of 
Microsoft.SharePoint.dll has been modified to inherit from the ASP.NET WebPart class 
instead. This versioning technique of changing a base class in a later version of an assembly is 
known as rebasing. The rebasing of the WebPart base class in Microsoft.SharePoint.dll is one 
of the keys to supporting older WSS-style Web Parts in a Windows SharePoint Services 3.0 
environment. 

If you look at the standard Web.config file for a Windows SharePoint Services 3.0 Web appli¬ 
cation, you’ll see that it contains configuration elements to redirect references from the Win¬ 
dows SharePoint Services 2.0 version of Microsoft.SharePoint.dll to the Windows SharePoint 
Services 3.0 version. This redirection in combination with the rebasing of the Windows Share- 
Point Services WebPart base class allows Web Part DLLs written for the Windows SharePoint 
Services 2.0 environment to run in the Windows SharePoint Services 3.0 environment with¬ 
out any need for recompilation. 

If you decide to move a Windows SharePoint Services 2.0 Web Part project to Microsoft 
Visual Studio 2005, you can continue to evolve your code using the same style as you have in 
the past and things will still work. However, you have another option once you have moved to 
Visual Studio 2005 and switched the project reference to Microsoft.SharePoint.dll to the new 
Windows SharePoint Services 3.0 version. Since the ASP.NET WebPart base class is now a part 
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of the inheritance hierarchy, you can change some aspects of your WSS-style WebPart class as 
if it were an ASP-style Web Part. This is known as a hybrid Web Part. 



Figure 1-6 The Windows SharePoint Services WebPart class has been rebased on Windows Share- 
Point Services 3.0 to inherit from the ASP.NET WebPart class. 

Enhancements in Content Storage 

One criticism that developers have had with Windows SharePoint Services 2.0 is that several 
valuable features supported with document libraries do not extend to lists. For example, doc¬ 
ument libraries support versioning and events, but lists do not. To address this criticism, the 
Windows SharePoint Services teams worked hard to extend the functionality of lists and 
bring them up to par with document libraries. With Windows SharePoint Services 3.0, lists 
support many of the same features as document libraries including versioning, events, and 
folders. There are also some new features in Windows SharePoint Services 3.0 supported by 
both lists and document libraries such as exposing data through automatic RSS feeds. 

Performance with large lists and document libraries has also been another concern with Win¬ 
dows SharePoint Services 2.0. For example, lists often start showing degraded performance 
when the number of items exceeds 2000. Document libraries have similar performance con¬ 
cerns. Fiowever, the rule of thumb for not exceeding 2000 documents applies to each folder 
within a document library as opposed to the document library itself. Therefore, coming up 
with a scheme to partition documents across multiple folders within a document library has 
come to be a popular approach in Windows SharePoint Services 2.0 for dealing with a large 
number of documents. 

Windows SharePoint Services 3.0 introduces a new column indexing feature to alleviate some 
of the performance problems just mentioned. From a list settings page or a document library 
settings page, you can add an index to any column. Doing this does not actually create a 
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physical index in SQL Server. Instead, it creates a table with the integer ID of the list item or 
document and the value of the indexed column. Windows SharePoint Services then uses this 
table to improve the performance of data returned from views, especially a view with a filter 
based on the indexed column. 

Many developers have expressed a desire to work with Windows SharePoint Services fields at 
a lower level to obtain more control over field rendering and validation. The Windows Share- 
Point Services team responded by adding extensible field types in Windows SharePoint Ser¬ 
vices 3.0. You can create an extensible field type by writing a class in C# or Visual Basic .NET 
that inherits from one of the built-in Windows SharePoint Services field types such as SPField- 
Text, SPFieldNumber, or SPFieldUser. An extensible field type can also utilize an ASP.NET User 
control that contains your favorite Web Controls. This allows you to use the same techniques 
for control initialization and validation that you have used in ASP.NET applications. 

Another nice innovation added to Windows SharePoint Services 3.0 is custom site columns. 
A site column is a reusable definition that can be used across multiple lists. A site column 
defines the name for a column, its underlying field type, and other characteristics such as its 
default value, formatting, and validation. Once you have defined a site column, you can then 
use it as you define the structure of your user-defined lists. An obvious advantage is that you 
can update the site column in a single place and have that update affect all the lists where the 
site column has been used. 

A site column is defined within the scope of a single site, yet it is visible to all child sites below 
the site in which it has been defined. Therefore, you can create a site column that is usable 
across an entire site collection by defining it in the top-level site. 

One convenient technique made available with the introduction of site columns is the ability 
to perform field lookups across sites. For example, you can create a site column in a top-level 
site that performs a lookup on a list in the same site. Then you can create other lists within 
child sites that use this site column to perform lookups on the list in the top-level site. There 
was no way to accomplish this task in Windows SharePoint Services 2.0 short of writing cus¬ 
tom code. 

Imagine you want to store several different types of documents in the same document library. 
For example, say you need to store customer presentations, customer proposals, and cus¬ 
tomer reports. What if you want each of these document types to have its own unique set of 
custom columns and its own unique event handlers? In Windows SharePoint Services 2.0, 
you can add extra columns and event handlers only to the document library itself, which 
always affects every document in that document library. Furthermore, a Windows SharePoint 
Services 2.0 document library can have only one associated document template. Windows 
SharePoint Services 3.0 introduces a powerful new storage mechanism known as content 
types to solve this problem. 

A content type is a flexible and reusable Windows SharePoint Services type that defines the 
shape and behavior for an item in a list or a document in a document library. For example, 
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you can create a content type for a customer presentation document with a unique set of col¬ 
umns, an event handler, and its own document template. You can create a second content 
type for a customer proposal document with a different set of columns, a workflow, and a dif¬ 
ferent document template. Then you can create a new document library and configure it to 
support both of these content types. The introduction of content types is significant to Win¬ 
dows SharePoint Services 3.0 because it provides an ability that did not exist in Windows 
SharePoint Services 2.0 to deal with heterogeneous types of content in lists and document 
libraries. 

Event Handlers 

While Windows SharePoint Services 2.0 provides support for event handlers, this support is 
fairly minimal and has generated a number of complaints from the developer community. 
Events in Windows SharePoint Services 2.0 are supported for document libraries but not for 
lists. Furthermore, Windows SharePoint Services 2.0 supports only asynchronous events that 
fire after the user’s action has been committed to the SQL Server database. This means there 
is no way for the developer to cancel a user’s action inside an event handler. 

Support for event handling improves in Windows SharePoint Services 3.0 by an order of mag¬ 
nitude. In addition to supporting the asynchronous events that exist in Windows SharePoint 
Services 2.0, there is now also support for synchronous events, which enables the developer 
to cancel the user’s action. For example, you can stop a user from deleting a document once 
it has been approved or from creating an order with an order date in the future. Furthermore, 
events are supported on list items as well as documents in a document library. 

You create an event handler by writing a custom class that inherits from one of the Windows 
SharePoint Services receiver classes and overriding methods to handle events. For example, 
to handle insert events for items in a list, you should create a class that inherits from the 
SPItemEventReceiver class and override the ItemAdding method, as shown in the following code. 

using System; 

using Microsoft.SharePoint; 
namespace Litware { 

public class MyReceiver : SPItemEventReceiver { 

public override void itemAddingCSPltemEventProperties properties) { 

SPWeb web = properti es .OpenwebO ; 

Guid Listld = properties.Listld; 

int Listltemld = properties.Listltemld; 

SPListltem Orders = web.Lists[Listld].GetltemByld(Listltemld); 

// check to make sure order date is not day in future 
DateTime OrderDate = Convert.ToDateTime(Orders["OrderDate"]); 
if (OrderDate.CompareTo(DateTime.Today) > 0) { 

string msg = "You cannot enter orders for future days"; 
properties.ErrorMessage = msg; 
properties.Cancel = true; 
return; 
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} 

} 

} 

} 

Now that you have seen how to write the code for a simple event handler, you’ll learn how to 
bind it to a particular list or document library. You can accomplish this either through writing 
code against the object model or by defining an event receiver in a Windows SharePoint Ser¬ 
vices feature. For example, you can bind this event receiver to a list using the following code. 

SPList list = web.Lists["Orders"]; 

list.EventReceivers.Add(SPEventReceiverType.itemAdding, 

"[Fully-qualified Assembly name]", 

"Litware.MyReceiver"); 

Windows SharePoint Services receiver classes use a naming convention for overridable meth¬ 
ods that differentiates synchronous and asynchronous events. For example, the ItanAdding 
event is a cancellable, synchronous event that fires before the change is made to the content 
database. These synchronous events provide a great way to validate column values as shown 
in the preceding event handler code on page 15. 

There is a complementary asynchronous event named ItemAdded that occurs after the change 
has been written to the content database. Unlike synchronous events, asynchronous events 
do not support cancelling the user’s actions. Instead they provide the means to perform a 
required operation after a change has been made to a document or list item such as assigning 
the value of a calculated column or sending an e-mail notification. 

In addition to supporting events on list items and documents, Windows SharePoint Services 
3.0 supports many other types of new events that were not available in Windows SharePoint 
Services 2.0. There are list events that fire when someone changes a list definition. For exam¬ 
ple, you can cancel the user’s action whenever someone tries to remove or rename a column 
in one of your custom lists. There are also events that fire whenever someone deletes or moves 
a site or an entire site collection. 

Workflows in Windows SharePoint Services 3.0 

Workflow applications have been getting quite a bit of attention at Microsoft lately. The 
WinFX run-time components to be released in fall 2006, named the Windows Workflow 
Foundation (WinWF), add a complete infrastructure for building workflow-style applica¬ 
tions. The WinWF infrastructure includes a workflow engine, pluggable components to per¬ 
sist workflow state, and a Visual Studio designer that makes it easy to create custom 
workflows by dragging components known as activities onto a workflow design surface. 

Windows SharePoint Services 3.0 builds on WinWF to provide a foundation for attaching 
business logic to list items and documents. Windows SharePoint Services 3.0 extended the 
basic workflow model of WinFX by associating a task list and history list with each workflow. 
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Windows SharePoint Services 3.0’s extensions to WinFX add a degree of responsibility and 
accountability to workflows that are human-oriented in nature such as a workflow for review¬ 
ing or approving a document. 

Both Windows SharePoint Services 3.0 and Office SharePoint Server 2007 ship with work- 
flows that are installed and ready to use out of the box. Windows SharePoint Services 3.0 
includes some simple routing workflows for things such as moderation and approval. Office 
SharePoint Server 2007 supplies workflows that are more complex and are used to support 
features such as its Web Content Management approval process. 

The creation of custom workflows represents an obvious extensibility point for developers 
creating business solutions with Windows SharePoint Services 3.0 and Office SharePoint 
Server 2007. In addition to the standard support of the Visual Studio Extensions for WinWF, 
the Office team also plans to ship a Windows SharePoint Services-specific workflow SDK and 
a workflow starter kit including Visual Studio project templates for creating custom work- 
flows targeted at Windows SharePoint Services 3.0 sites. 

Office SharePoint Designer 2007 also provides support for creating custom workflows in 
Windows SharePoint Services 3.0 sites. This support is designed more for the power user than 
developers because it provides a wizard to attach ad hoc business logic to list items and doc¬ 
uments in a production Windows SharePoint Services 3.0 site. 

Site Definitions, Features, and Solutions 

Developers and companies that have used Windows SharePoint Services 2.0 as a platform to 
build business solutions have found that working with low-level site definitions provides the 
greatest amount of control and reusability. A site definition is a directory on the front-end 
Web server containing XML files and .aspx page templates that define a blueprint for a site, 
including list schemas and page layouts. The XML-based language that is used inside many 
site definition files is called Collaborative Application Markup Language (CAML). 

Developers who have worked with Windows SharePoint Services 2.0 site definitions have 
voiced several criticisms. First, the XML files inside Windows SharePoint Services 2.0 site def¬ 
initions are poorly factored, making them unwieldy. Second, Microsoft doesn’t support evolv¬ 
ing a site definition in production once it has already been used to create sites. That means 
there isn’t a supported technique for site definitions to be used to add functionality to an 
existing Windows SharePoint Services 2.0 site. Third, site definitions and the custom assem¬ 
blies they depend on create deployment issues, because the files have to be pushed out to 
each front-end Web server in the farm without any assistance from the Windows SharePoint 
Services infrastructure. Finally, Windows SharePoint Services 2.0 provides no means to local¬ 
ize a site definition. This has been frustrating for companies that have wanted to internation¬ 
alize the business solutions they have built on top of Windows SharePoint Services 2.0. 
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The first significant enhancement in this area is the introduction of features. A feature is like a 
site definition in that it is a directory containing CAML-based XML files and page templates. 
However, features offer a much more modular approach because they are not required to 
define the blueprint for an entire site. Instead, a simple feature can define a single site element 
such as a custom list definition or a custom menu command that is to be displayed in one of 
the standard Windows SharePoint Services menus. 

A very attractive aspect of features is that they can be activated on an existing site. For exam¬ 
ple, you can create a feature that defines a custom list type, an instance of that list type, and an 
event handler or a workflow on that list instance. Once the feature has been installed, it can be 
activated in any site within a farm. Feature activation can be accomplished through the Win¬ 
dows SharePoint Services user interface, from the command line, or through custom code 
written against the Windows SharePoint Services object model. Once the feature has been 
activated, the site will have your new custom list and any behavior you want to attach to it. The 
key point is that features now allow you to add new types, storage, and functionality to exist¬ 
ing sites. 

Features also serve to make developing site definitions less unwieldy. In Windows SharePoint 
Services 2.0, each list definition had to be defined inside the context of a site definition. Now 
every list definition can be factored out into its own feature. Site definitions are now easier to 
create, as they can be composed using feature references. This is the approach that the Win¬ 
dows SharePoint Services team has taken with all the list types that ship as part of their collab¬ 
oration services. 

Windows SharePoint Services 3.0 introduces a new deployment mechanism called a solution. 
A Windows SharePoint Services solution is similar to Web Part packages from Windows 
SharePoint Services 2.0 in the sense that it is an aggregate CAB file containing XML instruc¬ 
tions and files that need to be deployed on each front-end Web server. However, Windows 
SharePoint Services solutions go beyond Web Part packages to support the deployment of 
features, site definitions, and related assemblies used for event handlers and workflows. 

Windows SharePoint Services 3.0 support for solutions also assists in pushing deployment 
files to each Web server in a farm. An administrator adds a solution to a Windows SharePoint 
Services farm, which copies the solution CAB file into the configuration database. Next, the 
administrator runs a command to deploy the solution, at which time Windows SharePoint 
Services starts a timer job to push the solution CAB file out to each front-end Web server and 
install it. 

One of the most welcome changes in Windows SharePoint Services 3.0 for developers is the 
new support for localization. Windows SharePoint Services 3.0 support for localization has 
been built on the localization infrastructure of ASP.NET 2.0. It is now possible (and recom¬ 
mended) to create site definitions and features in a language-neutral fashion and to maintain 
string literals in .resx files. Within the XML files and .aspx page template files of a feature or 
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site definition, you can acquire the value for a named string that has been localized into a .resx 
file using standard ASP.NET syntax. 

<%$Resources:Litware, MyString%> 

Internet-Style Security 

Authentication in Windows SharePoint Services 2.0 is based on Windows accounts and their 
associated Security IDs (SIDs). In a practical sense, this means that Windows SharePoint 
Services 2.0 is tightly coupled with Active Directory when used in anything but the smallest 
deployments. This dependency hasn’t been a problem for companies that have already 
deployed Active Directory when they started using Windows SharePoint Services 2.0 and 
Windows SharePoint Portal Server 2003 for building Intranet-based solutions. 

Using Windows SharePoint Services 2.0 and Windows SharePoint Portal Server 2003 has 
been more challenging for companies building extranet-based solutions. The tight coupling of 
Windows SharePoint Services 2.0 to Active Directory forces companies to create and maintain 
domain accounts for external users such as vendors and customers. It can also be said that 
Windows SharePoint Services 2.0 has gained a reputation as a product that isn’t appropriate 
for Internet-facing sites because most companies refuse to create Active Directory accounts for 
unknown users coming to the site for the first time from across the Internet. 

All this changes with Windows SharePoint Services 3.0 because authentication has been rede¬ 
signed on top of the new authentication provider infrastructure introducedwithASP.NET 2.0. 
If you don’t want to maintain user accounts for Windows SharePoint Services 3.0 and Office 
SharePoint Server 2007 sites inside Active Directory you can build or acquire an ASP.NET 
authentication provider that’s been designed to store and manage user accounts in a different 
identity repository. 

For example, ASP.NET 2.0 ships with the forms authentication provider that allows you to 
maintain user accounts in a SQL Server database. This authentication provider can be config¬ 
ured for use in a Windows SharePoint Services 3.0 site. With little effort on your part, you can 
put a Windows SharePoint Services 3.0 site on the Internet that allows unknown users to reg¬ 
ister themselves as members. ASP.NET 2.0 provides you with convenient support for creating 
and maintaining user accounts and even allows users to change and reset their passwords. 

Summary 

This chapter covered many of the significant advancements to Windows SharePoint Services 
3.0 that were targeted at developers. Once you to begin to dig in and work with Windows 
SharePoint Services 3.0, you will discover there are even more that could not be covered here. 
However, it should be clear that the Windows SharePoint Services 3.0 team has done a great 
job of listening to the criticism and feedback from developers about Windows SharePoint 
Services 2.0 and responding with some really significant advancements. 
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The next chapter takes a similar pass through new the developer-centric features introduced 
in Office SharePoint Server 2007. As you will see, there is a great deal of synergy between Win¬ 
dows SharePoint Services 3.0 and Office SharePoint Server 2007. The more you know about 
Windows SharePoint Services 3.0 development, the more power and control you will have 
when building custom solutions of top of Office SharePoint Server 2007. 
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Microsoft Office SharePoint Server 2007 provides portal and search features that represent 
the next generation of Microsoft Office SharePoint Portal Server 2003. However, Office Share- 
Point Server 2007 is much more than that. The Office team has made significant investments 
in many other areas to give Office SharePoint Server 2007 extra dimensions in Web content 
management, business intelligence, business process management, and enterprise content 
management, as shown in Figure 2-1 on the next page. This chapter describes the basic archi¬ 
tecture of Office SharePoint Server 2007 and explores the various opportunities for develop¬ 
ers building portal sites and business solutions. 

One of the most appealing aspects for developers is that Office SharePoint Server 2007 is built 
on top of Windows SharePoint Services 3.0 andASP.NET 2.0. Office SharePoint Server 2007 
portal sites are created using Windows SharePoint Services features and site definitions, and 
familiarASP.NET building blocks such as master pages and Web Parts. This means that Office 
SharePoint Server 2007 solutions can easily be extended withASP.NET components such as 
server-side controls and custom Web Parts as well as custom Windows SharePoint Services 
features containing things like custom list definitions, document libraries, event handlers, and 
workflows. 

It’s important to understand the extent of the synergy that exists between Office SharePoint 
Server 2007 and Windows SharePoint Services 3.0. Many of the new features in Office 
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SharePoint Server 2007 are made possible by new Windows SharePoint Services innovations 
described in Chapter 1, such as master page integration, content types, versioning, and 
workflows. 


Microsoft Office SharePoint Server 2007 
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Figure 2-1 Office SharePoint Server 2007 builds its functionality on top of ASP.NET 2.0 and Win¬ 
dows SharePoint Services 3.0. 

As a developer, it’s also important to set your expectations accordingly about what you’ll need 
to do to get an Office SharePoint Server 2007 solution up and running. Unlike many other 
development projects, you don’t usually start by firing up Microsoft Visual Studio. In some 
scenarios you can get an entire business solution up and running without ever writing any 
custom code. This is quite different from developing directly on the ASP.NET platform by 
itself where you need Visual Studio to put together the simplest site with a couple of pages 
and a navigation infrastructure. 

The Office team promotes a philosophy in which you begin building an Office SharePoint 
Server 2007 business solution with an “assemble and configure” mentality. Once you deter¬ 
mine the Office SharePoint Server 2007 features and services you want to utilize, you create a 
new portal site and do as much as possible by configuring services through browser-based 
administrative pages. If you are going to succeed at building Office SharePoint Server 2007 
solutions, it’s important to embrace this “assemble and configure” mindset to get as far as you 
can using out-of-the-box features. 

However, there will inevitably be times when you determine that the out-of-the-box experi¬ 
ence provided by Office SharePoint Server 2007 doesn’t cut it for a particular business solu¬ 
tion. Then you can put your developer’s hat back on and crank up Visual Studio 2005 to 
create many of the custom component types that are discussed throughout this chapter. 
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Building Office SharePoint Server 2007 Portal Sites 

Companies and developers can expect to find all the portal features in Office SharePoint 
Server 2007 that they have become accustomed to in SharePoint Portal Server 2003, such as 
user profiles, audience targeting, personal sites (that is, My Sites), search, and single sign-on. 
Office SharePoint Server 2007 also includes several new portal features, like the Business 
Data Catalog. 

If you have a background in building portal solutions on top of SharePoint Portal Server 2003, 
you will find that Office SharePoint Server 2007 is different in many ways. For example, 
SharePoint Portal Server provides its own separate administrative Web application for provi¬ 
sioning and configuring portal sites. Office SharePoint Server 2007, on the other hand, 
doesn’t require its own separate administrative application. Instead, Office SharePoint Server 
2007 integrates its administrative features and configuration links into the Windows Share- 
Point Services Central Administration application using the light-up features of Windows 
SharePoint Services 3.0. 

Office SharePoint Server 2007 is also quite different from SharePoint Portal Server under the 
hood. SharePoint Portal Server builds its portal site infrastructure around the concepts of 
“areas” and “listings.” However, areas in SharePoint Portal Server 2003 represent a strange 
and undocumented layer on top of Windows SharePoint Services 2.0 that has proved hard for 
developers to extend using standard Windows SharePoint Services development techniques. 
The concepts of areas and listings from SharePoint Portal Server 2003 have been eliminated in 
Office SharePoint Server 2007 and replaced with a portal infrastructure that was designed and 
implemented much more in line with Windows SharePoint Services best practices. 

An Office SharePoint Server 2007 portal site is a Windows SharePoint Services site collection 
containing a top-level site along with several child sites below it. Unlike SharePoint Portal 
Server 2003, a portal site does not have to be created at the root of an IIS Web site. This pro¬ 
vides more flexibility because you can host hundreds of portal sites inside a single IIS Web 
site. Remember that in Windows SharePoint Services 3.0 terminology, an IIS Web site 
extended with Windows SharePoint Services functionality is known as a Web application. 

You create a new Office SharePoint Server 2007 portal site the same way that you create any 
other new site collection through the Windows SharePoint Services Central Administration 
application, the Stsadm.exe command-line utility, or through custom code. When creating a 
new Office SharePoint Server 2007 portal site, you use one of the portal site templates created 
by the Office team. Here are some examples of site templates that can be used to create a new 
Office SharePoint Server 2007 portal site: 

■ Corporate Internet Site 

■ Internet Presence Web Site 

■ Publishing Site 
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The Office team has provided new site templates to create child sites within a portal site col¬ 
lection such as Report Center and Search Center. The Office team has also evolved some of 
the older SharePoint Portal Server 2003 site templates for use within Office SharePoint Server 
2007 portal site collections such as News, Topics, and the Sites Directory. 

Shared Service Providers 

The architecture of Office SharePoint Server 2007 is based on Shared Service Providers 
(SSPs). An SSP represents a set of services that can be configured a single time and shared 
across many different Office SharePoint Server 2007 portal sites and Windows SharePoint 
Services sites. Understanding SSPs is critical to being able to take advantage of Office Share- 
Point Server 2007 features and services. 

After you have finished installing Office SharePoint Server 2007 in a farm, you must explicitly 
create and configure one or more SSPs to take advantage of Office SharePoint Server 2007 
features such as user profiles, audiences, personal sites, Excel Services, the Business Data Cat¬ 
alog, and search. After you have initially created an SSP through the Windows SharePoint Ser¬ 
vices Central Administration pages, you can then configure the individual Office SharePoint 
Server 2007 services you need from the main SSP administration page shown in Figure 2-2. 
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Figure 2-2 An SSP allows you to configure Office SharePoint Server 2007 services. 


This new SSP architecture was designed to replace the Shared Services infrastructure of Share- 
Point Portal Server 2003 to provide greater flexibility in deployment and configuration. For 
example, it’s possible to create two different SSPs within the same farm and configure them 
differently, as shown in Figure 2-3. 





Building Solutions with Office SharePoint Server 2007 


25 



Farm 


Figure 2-3 Each Web application is associated with a Shared Service Provider. 

Each Web application in an Office SharePoint Server 2007 farm along with its Office Share- 
Point Server 2007 portal sites and Windows SharePoint Services sites is associated with 
exactly one SSP One Web application can be associated with one SSP while a different Web 
application can be associated with a second SSP. The search results from within one portal 
site might be very different from the search results within another portal site if they are asso¬ 
ciated with different SSPs that have been configured to have different content sources. 

User Profiles 

User profiles are an Office SharePoint Server 2007 feature that has been carried over from 
SharePoint Portal Server 2003 to track information about the users within an organization. 
User profiles allow users to discover and learn more about the people they work with and to 
see how everyone fits into their company’s organization chart. User profiles also provide the 
foundation for other Office SharePoint Server 2007 features such as audience targeting and 
personal sites. 

Once you have configured the user profile service through an SSP, Office SharePoint Server 
2007 stores the data for user profiles in Microsoft SQL Server. Office SharePoint Server 2007 
makes it possible to import and synchronize user profile data from external sources such as 
an Active Directory domain as well as other LDAP-based identity management systems. 

Office SharePoint Server 2007 provides several standard pages and Web Parts out of the box 
to display the information tracked within user profiles. Ligure 2-4 on the next page shows an 
example of how Office SharePoint Server 2007 displays a graphic representation of an organi¬ 
zation chart on a personal site from user data imported from Active Directory. Note also that 
the Office SharePoint Server 2007 object model provides an API to read and modify user pro¬ 
file data from components such as Web Parts, event handlers, and custom workflows. 

As with SharePoint Portal Server 2003, user profiles can be extended with custom properties 
to track user data for domain-specific business solutions. However, Office SharePoint Server 
2007 enhances custom properties by allowing for multivalued properties and properties 
defined with open or closed vocabularies. 
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Organization Hierarchy 

Patricia Doyle, 

President and Chief Executive Officer 
1“ Chris Preston, Chief Technology Officer 
sf. Andreas Berglund, 

Director of Computer Services 
^ LuisBonifaz, 

Technology Solutions Manager 
Brian Cox, Solutions Developer 
-David Yalovsky, Solutions Developer 
Sandeep Katyal, Solutions Developer 

Figure 2-4 A user profile can be used to show a company's organization chart. 

Audience targeting is another valuable Office SharePoint Server 2007 feature that has been 
carried over from SharePoint Portal Server 2003. You can define an audience by specifying cri¬ 
teria to define a subset of users. For example, you can create a Sales audience that is defined 
as all the users who are members of an Active Directory group named Sales. You could define 
another audience named Carpool as the set of users with the custom Car-pool property’s value 
set to True. 

Once you have defined an audience, you can then configure a Web Part to conditionally dis¬ 
play its content only when the current user is a member of that audience. This makes it 
straightforward to target content to those users who need it while hiding that content from 
users who would find it distracting. Audience targeting is also a great way to show privileged 
users links to secured pages while hiding these links from unprivileged users who would 
receive Access Denied errors when attempting to follow them. 

One more feature carried over from SharePoint Portal Server 2003 that is built on top of user 
profiles is personal sites. When personal sites are enabled within an SSP, Office SharePoint 
Server 2007 will provide each user with their own personal site (that is, a My Site) that is pro¬ 
visioned on demand the first time it is used. Personal sites enable users to edit certain aspects 
of their user profile to better describe themselves to their coworkers. A personal site has a pub¬ 
lic aspect, which makes it easy for a user to share data and documents with other users within 
the organization. A personal site also has a private aspect, allowing a user to store data and 
documents that are not meant to be shared. 

Office SharePoint Server 2007 Search 

Many people feel that the search feature is one of the most valuable aspects of Office Share- 
Point Portal Server 2003. Office SharePoint Portal Server 2003 Search makes it possible to 
search through not only content and documents within Office SharePoint Portal Server portal 
sites and Windows SharePoint Services team sites but also through external content such as 
Windows file shares, public Microsoft Exchange Server folders, and standard Web sites. 
Office SharePoint Server 2007 Search was designed to give you these same features in a man¬ 
ner that is more performance-oriented and easier to configure. 

With the previous version of SharePoint Technologies, Windows SharePoint Services 2.0 and 
SharePoint Portal Server 2003 each used a different underlying infrastructure to support 
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indexing and search. This created problems as companies upgraded from Windows Share- 
Point Services 2.0 to SharePoint Portal Server 2003. These upgrade problems have been 
addressed, as the Windows SharePoint Services Search Service and Office SharePoint Server 
Search Service are now based on the same underlying indexing and search infrastructure, 
which is an evolved version of what was provided by SharePoint Portal Server 2003. 

So what are the most significant differences between Office SharePoint Server 2007 Search 
and Windows SharePoint Services 3.0 Search? Office SharePoint Server 2007 Search makes it 
possible to search external content across the network such as Windows file shares and BDC 
data while Windows SharePoint Services 3.0 Search is limited to searching through content 
and documents within the current site collection. Also, Office SharePoint Server 2007 Search 
can be configured to run the indexing service and search service on different servers within a 
farm to increase scalability and throughput. Windows SharePoint Services 3.0 Search is lim¬ 
ited to running the indexing service and search service on the same physical server. 

Configuring Office SharePoint Server 2007 Search is an administrative exercise in creating 
and configuring content sources within the scope of a particular SSP A content source defines 
a set of searchable content. When you create a new SSP, Office SharePoint Server 2007 auto¬ 
matically creates a content source to search through user profile data as well as the content 
and documents within Office SharePoint Server 2007 portal sites and Windows SharePoint 
Services sites within the Web applications associated with the current SSP. However, the SSP 
administrator must explicitly create and configure additional content sources to support 
building indexes and searching through external content such as documents in a Windows 
file share or content from a public Web site. 

Windows SharePoint Services 3.0 and Office SharePoint Server 2007 provide a rich user inter¬ 
face for searching by adding search boxes and search result pages to each Windows Share- 
Point Services site and each Office SharePoint Server 2007 portal site. Office SharePoint 
Server 2007 goes even further to supply a dedicated child site named Search Center within a 
portal site collection that provides a specialized user interface for searching, as shown in Fig¬ 
ure 2-5 on the next page. 

From what you have just seen, you could conclude that companies can take full advantage of 
Office SharePoint Server 2007 Search facilities without ever writing any custom code. How¬ 
ever, Office SharePoint Server 2007 makes it possible for you customize how search results 
look by modifying the XSLT transforms it uses to display search results. Office SharePoint 
Server 2007 also exposes its search engine through a programmable API that enables devel¬ 
opers to extend either the Windows SharePoint Services 3.0 Search Service or the Office 
SharePoint Server 2007 Search Service using custom code. 

For example, you can write a server-side component such as a Web Part or a custom workflow 
that queries the Office SharePoint Server 2007 Search Service programmatically and deals 
with the returned search results in a customized fashion. Likewise, you can create a Windows 
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Forms application that queries the Office SharePoint Server 2007 Search Service from across 
the network through a built-in set of Web Services that ship as part of Office SharePoint 
Server 2007. 



The Business Data Catalog 

The Business Data Catalog (BDC) is a new innovative framework created by the Office team to 
provide Office SharePoint Server 2007 portal sites and standard Windows SharePoint Ser¬ 
vices 3.0 sites with integration into back-end line-of-business systems such as those created by 
SAP, Siebel, and PeopleSoft. The BDC additionally provides the means to integrate data 
directly from database systems such as SQL Server and Oracle. 

While SharePoint Portal Server 2003 makes it possible to integrate portal sites with back-end 
systems, it requires you to write custom code to manage connections and retrieve the data you 
need to display. Furthermore, the code you must write changes significantly as you switch 
between back-end systems from vendors such as SAP and PeopleSoft. The Office team 
designed the BDC to make things much easier. 

The BDC enables you to integrate data from back-end systems without requiring you to write 
custom code for managing connections and retrieving data. The design of the BDC is based 
on standardized metadata that describes the location and format of a back-end system and 
data entities defined inside. The BDC also provides an execution component capable of read¬ 
ing BDC metadata that is able to retrieve external data from any back-end system and return 
it to Office SharePoint Server 2007 in a standard format. 
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Figure 2-6 shows the high-level architecture of the BDC. As you can see, connectivity between 
the BDC and traditional line-of-business systems is achieved using standard Web services. 
Connectivity between the BDC and database systems is achieved usingADO.NET providers. 



Figure 2-6 The BDC provides seamless access to data in back-end line-of-business systems and 
databases. 

The first step in using the BDC is to author an XML file containing the metadata to connect to 
a back-end system. When you author metadata for the BDC, you define the data you want to 
retrieve in terms of entities. For example, you might define a customer as one entity and an 
invoice as another entity. The BDC metadata format also lets you define associations between 
entities in scenarios when there is a one-to-many relationship such as one that might exist 
between customers and invoices. 

The definition of a BDC entity contains identifiers, properties, and methods. The methods 
define how the BDC interacts with entry points exposed by the back-end system. For a back¬ 
end system accessible through Web services, methods define the names of the Web service 
operations and the parameters required to call them. For a back-end system that is a database 
such as SQL Server or Oracle, methods define the names of stored procedure and SQL 
statements. 

Entities can also define actions. A BDC action is used to dynamically parse together the URL 
behind a hyperlink that allows a user to navigate from a page in an Office SharePoint Server 
2007 portal site to another location. For example, an action defined on a BDC customer entity 
could be written to redirect users to a Web page in an SAP application that supports updates 
to customer information. Actions were designed to support scenarios where the BDC is used 
to display read-only data and to bootstrap the user into another application when updating or 
some other type of external operation is required. 
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Once you have authored or acquired the XML file with the required BDC metadata for a back¬ 
end system, you must import it into the BDC within the scope of a particular SSP to create 
what is known as a “BDC application.” You can accomplish this importing process using the 
SSP administrative Web pages. You can alternatively import an XML file with BDC metadata 
using custom code written against the BDC administrative object model. 

Once you have imported the required metadata to create a BDC application, there are several 
out-of-the-box techniques to leverage and display its data within a portal site. Office Share- 
Point Server 2007 ships with a set of Business Web Parts that can be quickly added to pages 
to query and display BDC data. You can also add new columns to lists and document libraries 
based on an entity defined in a BDC application. A user editing a column based on a BDC 
entity is automatically presented with a user interface making it possible to query the back¬ 
end system. 

The BDC has been designed to integrate with the Office SharePoint Server 2007 Search Ser¬ 
vice. For example, a back-end system and its entities can be defined as a content source so that 
the Office SharePoint Server 2007 indexing service will crawl through its data and build 
indexes for the Office SharePoint Server 2007 search engine. This becomes a powerful feature 
because it allows users to discover data from back-end systems about things like customers 
and invoices when running standard search queries through both Office SharePoint Server 
2007 portal sites and standard Windows SharePoint Services 3.0 sites. 

The BDC provides convenient features to map data from a BDC entity to properties in a user 
profile and to synchronize this data at periodic intervals. For example, if your company has an 
SAP system that contains employee data you like to include in user profiles, such as phone 
numbers or social security numbers, you can configure this type of data importing without 
writing any custom code. 

Finally, BDC entities can also be accessed programmatically using custom code written 
against the BDC object model. This makes it possible to write custom Web Parts as well as 
other server-side components and services that run their own BDC queries. One nice aspect of 
writing code to query BDC entities is that you don’t have to worry about managing connec¬ 
tions or whether you are accessing the back-end system through Web services or ADO.NET. 
All those details are abstracted away by BDC metadata and the BDC execution engine. 

Web Content Management 

Over the past few years, Microsoft’s strategy for publishing content on the Web has been 
based on Microsoft Content Management Server 2002 (CMS). CMS provides a structured way 
for content authors to add content to a company’s public Web site using professionally for¬ 
matted layout pages. CMS also provides a formalized scheme where a privileged user must 
approve any page modification before it can be seen by the Web site’s visitors. 
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In the past, many Microsoft customers have had to choose between CMS and SharePoint 
Portal Server 2003. While there is a connector that provides a certain degree of integration 
between CMS and SharePoint Portal Server 2003, these two products are built on very differ¬ 
ent architectures. This has resulted in frustration because you cannot build a site that fully 
benefits from both the CMS Web content management features and the SharePoint Portal 
Server 2003 portal features. 

Microsoft made an important decision to discontinue evolving CMS as a stand-alone product 
and to migrate CMS Web content management features and the CMS customer base over to 
Office SharePoint Server 2007. This will obviously have a significant impact on customers 
who have already become familiar with CMS development. However, the good news is that 
Microsoft’s Web content management strategy is now built on Windows SharePoint Services 
3.0 and Office SharePoint Server 2007. That means you can mix Microsoft’s best-of-breed 
Web content management features with its portal features in an Office SharePoint Server 
2007 portal site. 

If you have worked with CMS in the past, it’s important to note that the CMS concepts of 
channels and postings are not used in the Office SharePoint Server 2007 Web content man¬ 
agement infrastructure. Instead, the infrastructure has been designed using basic Windows 
SharePoint Services 3.0 building blocks such as child sites, page templates, content types, doc¬ 
ument libraries, and security groups. This newer approach lends itself to building custom 
solutions that extend the basic Web content management infrastructure using standard Win¬ 
dows SharePoint Services components such as custom event handlers and workflows. 

When you need to brand an Office SharePoint Server 2007 portal site, you can modify a single 
ASP.NET master page to customize the basic look and feel of the entire Web site just as you 
would in a standard Windows SharePoint Services 3.0 site collection. However, Office Share- 
Point Server 2007 extends Windows SharePoint Services 3.0 by introducing a publishing 
scheme based on page layouts. A page layout provides a structured approach to collecting 
content from content authors and displaying it on a page within a portal site. 

Examples of some of the page layouts provided by Office SharePoint Server 2007 out of the 
box include welcome pages, articles, and news items. An example of a page layout as seen by 
a content author in editing mode is shown in Figure 2-7 on the next page. As you can see, page 
layouts are designed to make it fairly straightforward to add and modify content from within 
the browser. You might also notice in Figure 2-7 that Office SharePoint Server 2007 provides 
a toolbar within the browser to give content authors and approvers a convenient way to move 
content pages through the editing and approval processes. 

Each page layout is based on a Windows SharePoint Services 3.0 content type and an associ¬ 
ated .aspx page template. By layering page layouts on top of content types, Office SharePoint 
Server 2007 makes it possible to add custom fields for storing different types of structured 
content such as HTML, links, and images. Once a custom field is defined inside the content 
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type associated with a page layout, it can be data-bound to the associated .aspx page template 
using another new Office SharePoint Server 2007 component known as a field control. 



Figure 2-7 Page layouts provide an editing mode for content authors. 


Office SharePoint Server 2007 ships with several field controls such as a rich HTML editor as 
well as others field controls for editing custom fields based on images and links. Many field 
controls also support adding extra declarative constraints to keep portal content within a 
highly structured format. 

Note that the page layout infrastructure is very extensible because Windows SharePoint Ser¬ 
vices content types support inheritance. It’s fairly straightforward to take one of the built-in 
page layouts and customize it by extending its underlying content type or .aspx page tem¬ 
plate. 

In addition to field controls, an .aspx page template for a page layout can also contain 
ASP.NET server controls and Web Part zones. A page layout with Web Part zones provides the 
content author with the flexibility to add Web Parts displaying content outside the schema of 
the current page layout. In addition, Office SharePoint Server 2007 provides several Web 
Parts that have been designed for use in portal pages including the Table of Contents Web 
Part and the Content Query Web Part. 

The .aspx page templates associated with page layouts are stored along with the portal site’s 
master page in the Master Page Gallery. The Master Page Gallery also contains a metadata col¬ 
umn to associate each .aspx page template with a content type. Note that it is possible to have 
multiple page layouts, each with its own .aspx page template, that are all associated with the 
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same content type. This is useful when you want to create several different views for the same 
set of structured content. 

Whenever a content author creates a new content page from a page layout, Office SharePoint 
Server 2007 creates a new instance of the associated content type and stores it in a document 
library named Pages. When a content author updates content for custom fields within a page 
layout, Windows SharePoint Services stores the data within a structure defined by the under¬ 
lying content type. The fact that content page instances are stored in a Windows SharePoint 
Services document library means that the Office SharePoint Server 2007 Web content man¬ 
agement infrastructure can take advantage of basic document library features provided by 
Windows SharePoint Services 3.0 such as versioning, auditing, approval, and workflows as 
well as per-document security configuration and security UI trimming. 

By default, Office SharePoint Server 2007 uses the basic document approval features of a Win¬ 
dows SharePoint Services document library to control when the updated content is shown to 
the site’s visitors. However, the infrastructure was designed to make it straightforward to asso¬ 
ciate custom workflows with the Pages document library for scenarios where you need some¬ 
thing more sophisticated than the Office SharePoint Server 2007 content approval 
functionality that comes out of the box. 

Note that an instance of a content page stored in the Pages document library does not repre¬ 
sent a copy of the page template. Instead, it contains redirection logic to link it to the .aspx 
page template at run time. That means updating the .aspx page template will always affect 
content pages that have already been created from the associated page layout. 

A number of other Office SharePoint Server 2007 features focus on Web content manage¬ 
ment. I will conclude this section by quickly exploring what these features are and why they 
are valuable. 

Office SharePoint Server 2007 provides a framework for document converters. A document 
converter is a component designed to read content from an external format such as a 
Microsoft Word document and convert it into a format that can be displayed within an Office 
SharePoint Server 2007 content page. Several document converters will ship with Office 
SharePoint Server 2007 as well as a framework for building and integrating custom document 
converters. 

Office SharePoint Server 2007 provides content deployment features that allow you to trans¬ 
fer content from one site collection to another. This is valuable for companies that prefer to 
author content in a staging environment before moving it into their production environment. 
You take advantage of Office SharePoint Server 2007 content deployment features by config¬ 
uring paths and jobs. 

A path defines one site collection as a content source and another site collection as a content 
destination. Once you have defined a path, you can define one or more jobs to move content 
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from the source to the destination. Jobs can be run on demand or they can be scheduled to 
run at a future time or on a periodic basis. 

Office SharePoint Server 2007 also supports a feature known as site variations for companies 
that need to duplicate a site’s content for translation into multiple spoken languages or for 
targeting different types of rendering devices. For example, imagine you have configured 
Office SharePoint Server 2007 variation support for German and French in addition to Span¬ 
ish. Office SharePoint Server 2007 maintains a parallel structure across these three different 
sites with respect to pages and child sites. 

When a content author adds a new page to the master variation site maintained in Spanish, 
Office SharePoint Server 2007 automatically adds the same page into the structure of the 
other sites as well. Office SharePoint Server 2007 can also be configured to create a Windows 
SharePoint Services task marking the required translation as a to-do item for a language trans¬ 
lator. While Office SharePoint Server 2007 will not actually convert your content from one 
spoken language to another, it does keep multiple sites in sync with respect to their content 
structure, which provides a good deal of value. 

Office SharePoint Server 2007 provides several caching options. While Office SharePoint 
Server 2007 doesn’t allow you to use ASP.NET output caching directives the same way you 
do in a standard ASP.NET page, it provides a more sophisticated framework to reach the 
same end. 

You can enable Office SharePoint Server 2007 output caching at the site collection scope. 
When using these caching features, you configure caching profiles to control caching page 
items and complete pages in memory. Developers should take note that Office SharePoint 
Server 2007 supplies dedicated caches for navigation nodes and content returned from poten¬ 
tially expensive retrieval operations such as standard Windows SharePoint Services queries 
run using an SPQuery object and cross-site queries run using a SharePoint Portal Server 
SPSiteDataQuery object. 

Office SharePoint Server 2007 also supports Web front-end (WFE) disk caching. If you enable 
the WFE disk cache, Office SharePoint Server 2007 will begin writing the large files it retrieves 
from the SQL Server database into a special cache on the local file system of the front-end Web 
server. This eliminates the need to continually move .jpg, .png, .gif, .css, and .js files from the 
SQL Server database server to front-end Web servers on a per-request basis. 

Finally, it’s important to note that Office SharePoint Server 2007 publishing sites benefit from 
Windows SharePoint Services 3.0 security advancements. In particular, Windows SharePoint 
Services 3.0 is built on top of the ASP.NET 2.0 authentication provider infrastructure. Unlike 
SharePoint Portal Server 2003, which is tightly coupled to Active Directory, you can configure 
an Office SharePoint Server 2007 portal site to use forms-based authentication. That means 
you can store the user credentials in a SQL Server database or another LDAP identity manage¬ 
ment system of your choosing. 
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Business Intelligence Features 

In the past, the Office team has provided its customers with business intelligence (BI) features 
in SharePoint Portal Server 2003, the Office 2003 Web Parts and Components Add-in, and 
Microsoft Office Business Scorecard Manager 2005. Over the past few years, many developers 
have used these BI products as a platform for building dashboard-style applications that pro¬ 
vide upper-level management with up-to-date data that reflects the health of a business and 
flags potential problems in a timely matter. 

Leveraging their previous experience with these earlier BI components, the Office team has 
designed Office SharePoint Server 2007 to include a next-generation platform for building 
dashboards and integrating with other technologies in the greater Microsoft BI picture such as 
Microsoft Office Excel 2007, Microsoft SQL Server Reporting Services, and Microsoft SQL 
Server Analysis Services. As with all other aspects of Office SharePoint Server 2007, its BI plat¬ 
form builds on top ofASP.NET and Windows SharePoint Services 3.0 and provides many 
opportunities for extending what comes out of the box. 

The Office team has heard consistent customer feedback telling them that a large percentage 
of corporations maintain a significant amount of business logic in Excel spreadsheets and that 
this business logic has been hard to leverage and reuse across a large organization. This feed¬ 
back led the Office team to create Microsoft Office SharePoint Server 2007 Excel Services. 

Excel Services represents a server-side version of the traditional Excel calculation engine that 
has been rewritten from the ground up on top of Windows SharePoint Services 3.0. Excel Ser¬ 
vices doesn’t suffer from the same types of scalability problems that occur when you run the 
desktop version of Microsoft Excel on the server. 

Excel Services also provides a sever-side rendering engine that can display spreadsheets in the 
browser as HTML. That means a company can store all its Excel spreadsheets in a centralized 
document library and make them viewable by users who don’t even have Excel installed on 
their desktop. Furthermore, users can see the numbers displayed by a spreadsheet within the 
browser without having any access to the business logic behind it that represents a company’s 
intellectual property. 

A key observation is that the Microsoft Office 2007 system introduces a new paradigm that 
recognizes that companies maintain business logic within Excel spreadsheets just as they 
maintain business logic within managed code inside compiled assemblies and within stored 
procedures in a SQL Server database. To support this new paradigm, the Office team has 
added many new features to Office 2007 products designed to expose and update this busi¬ 
ness logic as well as to protect its intellectual property from prying eyes. 

The new desktop version of Office Excel 2007 has been enhanced to allow information work¬ 
ers with Excel expertise to publish and update their spreadsheets in a document library on an 
Office SharePoint Server 2007 portal site or a Windows SharePoint Services team site. Users 
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running a version of Excel can view these spreadsheets through a rich client experience while 
other users can rely on Excel Services to view the same spreadsheet inside the browser. 

Note that this new spreadsheet publishing metaphor allows a company to maintain a single 
master copy of its critical spreadsheets. It also allows the spreadsheet author to post updates 
without the need to involve the development staff or the IT staff. 

It’s important to note that the use of Excel Services isn’t restricted to the browser. You can cre¬ 
ate a Windows Forms application that leverages the server-side Excel calculation engine but 
doesn’t use the rendering engine. For example, a Windows Forms application can use out-of- 
the-box Web services from Excel Services to load a spreadsheet on the server, enter input 
data, perform calculations, and return a result. This example furthers the analogy that Excel 
Services exposes the business logic defined in a spreadsheet just as SQL Server exposes the 
business logic defined in a stored procedure. 

Office SharePoint Server 2007 provides a special site template named Report Center for com¬ 
panies that want to build dashboard-style applications. Report Center was designed to make 
the new BI features of Office SharePoint Server 2007 easy to discover and use. A Report Cen¬ 
ter site contains a document library named Reports Library that is tuned for storing and dis¬ 
playing BI reports such as Excel spreadsheets and reports built for SQL Reporting Services. 

Another important aspect of Report Center is the built-in support for creating and importing 
Key Performance Indicators (KPIs). A KPI is a common term used in the BI space to describe 
a visual indicator that tells a manager how some aspect of the business is doing. For example, 
the KPI for a product inventory level might display a green light when there is enough inven¬ 
tory to supply all the orders for the coming week. 

However, the light might turn from green to yellow when the inventory level drops below 
some predefined threshold such as the amount of inventory required to supply orders for the 
next four days. The light then might change from yellow to red when the inventory level drops 
to a point where it will run out within the next 48 hours. The main idea is that a KPI flags busi¬ 
ness problems that require immediate attention. 

Office SharePoint Server 2007 provides out-of-the-box support for creating several different 
types of KPIs. For example, you can create a KPI whose indicator changes automatically 
depending on data it dynamically reads from a Windows SharePoint Services list or an Excel 
spreadsheet. Office SharePoint Server 2007 also provides integration support for KPI in SQL 
Server 2005. That is, if you have already created KPIs with SQL Server Analysis Services, you 
can import and display them on a Report Center site alongside other types of supported KPIs. 

The last aspect of Report Center I want to discuss is the built-in framework for filtering data 
before it’s shown to the user. This is a key component of the Office SharePoint Server 2007 
dashboard framework because it makes dashboard pages more relevant to the user. 

When a manager visits a Report Center site, the experience is enriched if the dashboard views 
have been customized with data that is relevant for that user. For example, a sales manager for 
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the Eastern region can be presented with a different view of sales figures than the sales man¬ 
ager for the Western region. Furthermore, managers like to be able to see high-level data at 
first and then be able to drill down into more specific categories on demand. 

Filtering support is built into Office SharePoint Server 2007 dashboards at the page level 
using Web Part connections. Office SharePoint Server 2007 supplies Web Parts out of the box 
that allow page designers and users alike to specify criteria such as the name of the current 
user, a date range, or a product category. There are also many out-of-the-box Web Parts that 
can be configured to consume the filtering criteria supplied by other Web Parts such as the 
standard Windows SharePoint Services Fist View Web Part as well as the Web Parts designed 
for use with the Business Data Catalog, Excel Services, SQF Reporting Service, and SQF Anal¬ 
ysis Services. 

Managing Documents and Business Processes 

In past versions of Microsoft Office Word, Excel, and PowerPoint, Microsoft has relied on a 
default file structure that is based on binary files written in a proprietary format. These for¬ 
mats have been very hard to read and modify unless you go through the object model of the 
hosting Office application such as Word or Excel. As a result, companies have tried to run 
Office desktop applications on the server, which poses serious problems with scalability and 
robustness. 

Office 2000 and Office 2003 added some modest capabilities for creating Excel spreadsheets 
and Word documents using XML. In the 2007 Microsoft Office system, Microsoft has taken 
this idea much further by adopting the Open XML Formats for Word, Excel, and PowerPoint 
documents. The Open XML Formats is a new file standard for creating composite documents 
containing multiple inner XML files that factor out content from other aspects of the docu¬ 
ment such as formatting instructions, data, and code. 

The top-level file in the Open XML Formats is known as a package and it is structured using 
standard ZIP file technology. The internal files contained within a package are known as parts. 
Many parts within Word, Excel, and PowerPoint files contain XML structured in accordance 
with published XML schemas. Other parts within a package can consist of binary files for 
items such as graphics, audio clips, and videos. 

A major goal of the Open XML Formats is to provide a standard approach for reading, manip¬ 
ulating, and generating documents in server-side scenarios where using the object model of a 
desktop application such as Word or Excel isn’t a viable option. Think about a scenario in an 
Office SharePoint Server 2007 portal site when you have created and configured an event han¬ 
dler to fire whenever someone uploads a new Word document. The new Open XML Formats 
make it significantly easier to exact data or to perform hygiene on the document such as 
removing comments and personal information. You can also leverage Open XML Formats to 
develop server-side components that generate Office documents on the fly using data pulled 
from content sources such as a Windows SharePoint Services list or the Business Data Catalog. 
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To get started working with the Open XML Formats, you need to learn how to program 
against the new WinFX packaging API. This is the recommended API to use when opening 
and creating packages. You must also learn the specific package structure and XML schemas 
for the type of Office document you are working with. These details will change as you move 
among Word, Excel, and PowerPoint documents. Microsoft has started a developer commu¬ 
nity effort around the Open XML Formats at http://openxmldevdoper.org. 

Office Forms Server 2007 

Since the introduction of Microsoft Office 2003, many companies have found that Microsoft 
Office InfoPath provides a quick and efficient solution for creating electronic input forms to 
collect XML-based data from users. The InfoPath 2003 forms designer provides high levels of 
productivity because it significantly reduces or eliminates the need to write custom code 
when developing forms. InfoPath also creates a very reliable way to collect data because 
InfoPath forms are built on top of XML schemas, allowing them to automatically validate the 
user’s input. 

InfoPath 2003 provides a convenient integration point with Windows SharePoint Services 2.0 
where a form designer can publish an InfoPath form on a Windows SharePoint Services site, 
creating what is known as a forms library. A forms library is a hybrid Windows SharePoint Ser¬ 
vices document library that uses an InfoPath form template as its underlying document tem¬ 
plate and acts as a repository for XML documents containing form data entered by users. 

One common complaint that Microsoft has received about this forms-based technology is that 
it requires a full version of InfoPath to be installed on the user’s desktop. This is true not only 
for those designing forms but also for any users who need to read or modify data in an 
InfoPath form. The problem is that the features of InfoPath 2003 do not extend to users for 
whom deploying Office 2003 on their desktop isn’t an available option. Office SharePoint 
Server 2007 introduces Microsoft Office Forms Server 2007 to solve this problem. 

Office Forms Server 2007 has been designed to render InfoPath forms within the browser to 
reach users who are not running InfoPath. In fact, Office Forms Server 2007 doesn’t even 
require users to be running a version of Microsoft Internet Explorer or the Windows operat¬ 
ing system. The Office team is testing Office Forms Server 2007 for compatibility with brows¬ 
ers such as Firefox, Safari, and Netscape as well as several other HTML-enabled mobile devices. 

You can use the Office InfoPath 2007 forms designer to create Web-enabled forms, which can 
then be deployed to Office Forms Server 2007. This forms designer provides a compatibility 
checker to ensure that your forms contain only controls and elements that are compatible 
with what Office Forms Server 2007 can render to the browser. It’s also possible to create and 
deploy InfoPath forms intended for dual use. Such a form is downloaded to the desktop and 
loaded into the rich client environment when InfoPath is available on the desktop or other¬ 
wise rendered through the browser when necessary. 
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Enterprise Content Management 

Over the past few years, governments and other regulatory organizations have placed increas¬ 
ingly restrictive requirements on companies that generate and store large numbers of docu¬ 
ments. The Sarbanes-Oxley Act and emerging privacy laws within the U.S. have made it much 
harder for companies to stay within acceptable levels of compliance. Office SharePoint Server 
2007 provides several enterprise content management features to address these problems. 

Many of the Office SharePoint Server 2007 features for enterprise content management are 
built on top of the new information policy feature. An information policy is a Windows Share- 
Point Services component that can be enabled and configured within the scope of a list or doc¬ 
ument library. Out-of-the-box examples of information policies that ship with Office 
SharePoint Server 2007 include those for document expiration, auditing, and the automatic 
generation of bar code labels to identify physical documents and associate them with elec¬ 
tronic copies maintained in a document library. 

The Windows SharePoint Services framework for information policies was designed with 
extensibility in mind. For example, you can create a custom policy that checks the integrity of 
a digital signature on every document within a document library. You can create another pol¬ 
icy that promotes document hygiene and privacy by removing all the comments and personal 
information from documents as they are uploaded to a document library. 

Office SharePoint Server 2007 provides a dedicated site template named the Records Reposi¬ 
tory to assist with records management. A Records Repository site provides archiving support 
for companies that are required to keep certain types of business documents as official 
records of the company’s activities. While archiving requirements vary across different regu¬ 
lated industries, keeping records is required to provide evidence of a company’s activities in 
the event of a litigation dispute or an audit. 

The Single Sign-On Service 

The final topic I would like to cover is the Single Sign-On (SSO) Service. The SSO that ships 
with Office SharePoint Server 2007 is an enhanced version of the credential-mapping service 
that ships with SharePoint Portal Server 2003. The SSO is used to map the identity of a user 
who has logged on to an Office SharePoint Server 2007 portal site with another identity for 
the same user in a back-end system. 

For example, imagine a user named Bob has two user accounts. First, he has a Windows 
account in Active Directory that he uses to log on to the local network and to authenticate 
against the Office SharePoint Server 2007 Web server. Bob also has a second user account 
with different credentials he needs to use when accessing the company’s back-end SAP 
application. 

SSO solves the problem of allowing server-side code running on behalf of Bob to seamlessly 
access the SAP system using his secondary account once he has logged on to the Office Share- 
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Point Server 2007 portal site using his primary Active Directory account. SSO accomplishes 
this by providing a credential-mapping database to store his SAP user name and password in 
an encrypted format. SSO also provides the means for custom Web Parts and other Office 
SharePoint Server 2007 services such as the BDC, Excel Services, and Office Forms Services to 
retrieve user credentials that are required when accessing various back-end systems. 

Summary 

The chapter has provided a broad survey of the most significant services and features pro¬ 
vided by Office SharePoint Server 2007. You have seen that the Office team has invested 
heavily to provide Office SharePoint Server 2007 functionality in areas such as portal and 
search, Web content management, business intelligence, business process management, and 
enterprise content management. 

You have also seen that Office SharePoint Server 2007 promotes an “assemble and configure” 
philosophy that enables you to construct rich business solutions without ever starting Visual 
Studio or writing a line of managed code. However, you should always remember that Office 
SharePoint Server 2007 is built on top ofASP.NET 2.0 and Windows SharePoint Services 3.0, 
providing ample opportunities for extending standard functionality with custom components 
such as Web Parts, event handlers, workflows, page layouts, document converters, and server- 
side forms. 
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This chapter serves as a bridge to the chapters that follow, in which you’ll see examples that 
illustrate some of the features, architectural underpinnings, and development possibilities 
related to Microsoft Windows SharePoint Services 3.0 and Microsoft Office SharePoint 
Server 2007. 

In this chapter, we’ll walk through how to set up and build a basic SharePoint site. The exam¬ 
ple will let you see some of the administrative pages and other elements of the user interface 
in the latest version of Windows SharePoint Services. In the example, we’ll create a site collec¬ 
tion and a top-level team site, a list for tracking projects, and a document library for storing 
files related to projects. The site will also include two child sites. You’ll see how to change the 
look and feel of a SharePoint site and, in the last section of the chapter, you’ll see some sample 
code for a custom Web Part. 

Creating a Site Collection and a Top-Level Site 

The first step in creating a site collection and a top-level site is to open the SharePoint Central 
Administration page. (Choose Start, Administrative Tools, SharePoint 3.0 Central Administra¬ 
tion.) On the Central Administration home page, click Application Management at the top of 
the page, and then, on the Application Management page, under SharePoint Site Manage¬ 
ment, click Create Site Collection. 

After the Create Site Collection page appears, the Select Web Application dialog box (shown 
in Figure 3-1 on the next page) opens and prompts you to select the target Web application 
(formerly known as a virtual server) that will be used to provision the new site collection. 
Choose the default Web site as the target Web application or a different target if necessary. 
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Figure 3-1 Use the Select Web Application dialog box to specify the Web application that will 
provision the site collection. 

Back on the Create Site Collection page, fill in the information required to create a new site 
collection, using settings similar to the following. When filled in, the Create Site Collection 
page would look something like Figure 3-2. 

■ The new site collection’s URL (http://ossl/sites/projectmanagement). 

■ The primary site collection owner (litwareinc\administrator, with an e-mail address of 
administrator@litwareinc.com). 

■ The Quota Template option set to No Quota, the default setting. 

■ The site template that will be used for the sites in the site collection. (Blank Site is 
used in this example as the site template for the new top-level site that is automatically 
created.) 

After you click OK to create the site collection and top-level site, you’ll see a page confirming 
that the site has been created. You can then navigate to the top-level site by using the browser. 
Figure 3-3 shows the bare-bones site. 
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Figure 3-2 

You specify information such as this to define a site collection. 




Figure 3-3 The top-level site of the site collection 



44 


7 Development Projects for Microsoft Office SharePoint Server 2007 and Windows SharePoint Services 


At this point, well make a few straightforward changes to the settings and appearance of the 
top-level site. For example, well change the site’s title and add our own graphics. 

Start by clicking Site Settings on the Site Actions menu. On the Site Settings page, in the Look 
And Feel section, click Title, Description And Icon. On the General Settings page, enter the 
title for the new site: LW Project Management. 

We can also use this page to point to different graphics files to replace the standard Microsoft 
graphics. For example, you can modify the site icon to use a custom graphic. The graphics 
files you want to use for a site should be located within the Windows SharePoint Services 
_layouts directory so that the graphics files are accessible to all SharePoint sites within a farm. 
In particular, copy the graphics to the following location: 

C:\Program Files\Common Files\Microsojt Shared\web server extensions\12\ 
TEMPLATE\IMAGES 



Note Windows SharePoint Services configures the IMAGES directory with Internet Informa¬ 
tion Services so that it is a child virtual directory of the Jayouts virtual directory. This configu¬ 
ration means that your graphics files should be accessible within any SharePoint site using a 
relative URL that looks like the following: 

/Jayouts/images/LitwareGraphics/LitwareLogo.png 


While still on the General Settings page, we can modify the address for the logo image file, 
entering a value something like /_layouts/images/LitwareGraphics/LitwareLogo.png. Click 
OK on the General Settings page, and you can then confirm that pages within the site now dis¬ 
play the new title and the new site icon, as you can see in Figure 3-4. 

We can also change the look and feel of the site by modifying the Site Image Web Part on the 
site’s home page so that it displays a custom graphic instead of the default Microsoft graphic. 
To do this, we place the home page of the site in edit mode by choosing Edit Page from the 
Site Actions menu. After the page is editable, select Modify Shared Web Part from the Site 
Image Web Part’s action menu. You’ll then see a task pane in the browser that allows you to 
modify the Image Link property. Assign the Image Link property a value such as /_layouts/ 
images/LitwareGraphics/LitwareSlogan.png, and then click OK. Figure 3-5 shows the site’s 
home page displaying the new site graphic. 
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Creating a List for Tracking Project Profiles 

In this example, we’ll create and modify a custom SharePoint list that will be used to manage 
information about consulting projects. Start by clicking Create on the Site Actions menu to 
open the Create page. In the Custom Lists section, click Custom List to open the page shown 
in Figure 3-6 that you use to name the list. Well name the list Projects, and then click Create. 
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Figure 3-6 This page is used to create a custom list. 


Now we want to modify some properties of the Projects list. On the list’s Allitems.aspx page, 
click List Settings on the Settings menu to open a page with the helpful title Customize 
Projects. On this page, click Advanced Settings in the General Settings section. On the 
Advanced Settings page for the Projects list, shown in Figure 3-7, take note of the different 
modifications you can make to the list, such as enabling item-level permissions, allowing 
attachments to list items, and so on. The one change well make to the Projects list is to disable 
attachments because the structure and purpose of the list doesn’t require them. 
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Figure 3-7 Use this page to set properties for a list. 


Well next use the List Settings page to add and modify the columns that will make up the 
Projects list. Using the links in the Columns section of the List Settings page, well structure 
the Projects list with the columns shown in the following table. 


Column Name 

Type 

Notes 

Project 

Single Line of Text 

You do not need to create this column. Instead, 
you can rename the Title column (one of the 
default columns) as Project. 

Client 

Single Line of Text 

This is a required column. 

Contract Signed 

Yes/No 

The default value is set to No. 

Contract Amount 

Currency 

Currency formatting can be set to whatever seems 
most appropriate. 

Begin Date 

Date and Time 

This column is formatted to show only the date. 

End Date 

Date and Time 

This column is formatted to show only the date. 

Created By 

Person or Group 

You do not have to create this column. It is created 
when you create a new list. 

Modified By 

Person or Group 

You do not have to create this column. It is created 
when you create a new list. 
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Figure 3-8 shows the Projects list with some test data entered. 
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Figure 3-8 The Projects list with its column definitions and some test data 


Creating a Document Library 

In the following example, well add a document library to the Project Management site that 
can be used for storing and managing documents. 

We start by clicking Create on the Site Actions menu to open the Create page. In the Docu¬ 
ment Libraries section, click Document Library to open the page on which you provide a 
name for the document library. Well name the library Project Documents. Now that we’ve 
created the document library, we can make the use of it more particular by adding a column 
to associate custom metadata with each document that is added to the library. 

On the document library’s Allitems.aspx page, on the Settings menu, click Document Library 
Settings. This command takes you to a page named Customize Project Documents. Well add 
a column named Project to the document library that is a lookup column. The source for this 
column will be the Project column from the Projects list. In creating this column, we also 
select the option to make the Project column required. Figure 3-9 shows the settings for the 
Project lookup column. 
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Figure 3-9 Settings for a document library column that looks up project names 


We can now upload a few documents to test out the Project Documents document library. As 
you might expect, whenever a document is uploaded to the Project Documents document 
library, Windows SharePoint Services displays a page that prompts a user to assign a value to 
the Project column. Windows SharePoint Services forces users to associate each and every 
document that is stored in this document library with a specific project. 

Customizing the Home Page 

One of the steps you’ll often want to take when designing and developing navigational 
aspects of a SharePoint site is to specify the items that appear on the Quick Launch toolbar on 
the left side of the home page. 

To customize this control, start by clicking Site Settings on the Site Actions menu. On the Site 
Settings page, click Quick Launch in the Look And Feel section. On the Quick Launch page, 
you can add, edit, and delete links and headings from the Quick Launch control. In this case, 
we’ll remove the headings for Pictures, Discussions, and Surveys. After these modifications, 
the Quick Launch toolbar looks like Figure 3-10 on the next page. 

Next we’ll add two Web Parts to the home page, one to display the Projects list, and a second 
to show the Project Documents document library. To add these Web Parts, we place the site’s 
home page in edit mode by choosing Edit Page from the Site Actions menu. Next we click Add 
A Web Part at the top of the left Web Part Zone. In the Add Web Parts dialog box, select the 
items for the Projects list and the Project Documents document library, and then click Add. 
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After you have added Web Parts to a page, as shown in Figure 3-11, you can experiment by 
moving them between zones and changing some of their Web Part properties. 
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Figure 3-10 The customized Quick Launch toolbar 
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Creating Child Sites 

Well continue building the Project Management team site by adding two child sites that are 
used to track departmental or divisional information within the organization. Keep in mind 
that when you create child sites, you want to make it easy for users to navigate between the 
top-level site and a child site, between child sites, and back again. To handle this need, you can 
create a top link bar that appears on the parent site and on child sites, similar to the one 
shown in Figure 3-12. 



Figure 3-12 The top link bar is used to navigate between sites in a collection 


Start by clicking Create on the Site Actions menu. On the Create page, under Web Pages, click 
Sites And Workspaces. This link takes you to a page on which you can create a child site. In 
our example, we’ve named the first child site North Division. The site’s URL is http://ossl/ 
sites/ProjectManagement/NorthDivision. We’ve used the Blank Site as the site template. In 
the Navigation section of the New SharePoint Site page, select Yes for the option Use The Top 
Link Bar From The Parent Site. Also select Add To Top Link Bar. As we did with the Project 
Management home page, we can modify the Site Image Web Part for the North Division site 
so that it displays a custom graphic instead of the default Microsoft graphic. 


Setting up the child site for the South Division follows the same steps. At this point, you 
should be able to navigate between the top-level site and either child site with a single click on 
the top link bar. 
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Creating a "Hello World" Web Part 

In this section, you’ll see how to develop a simple custom Web Part in Microsoft Visual Studio 
2005. Figure 3-13 shows a view of the class library DLL project that we’ll work with, which is 
included in a solution named LitwareWebPartsLab. 



Figure 3-13 The LitwareWebPartsLab solution 


The LitwareWebPartsLab project is a class library project that is configured to build an assem¬ 
bly DLL with a strong name. Here is the code from the AssemblyInfo.es file that describes the 
format for the name of the output assembly DLL: 

using System.Reflection; 

// if needed, copy Assembly format name from below to paste elsewhere 
// LitwareWebPartsLab, version=l.0.0.0, Culture=neutral, 

// PublicKeyToken=d4e5777bl6a5749f 
[assembly: AssemblyversionC'1.0.0.0")] 

// this was used to get around a beta 1 bug for importing web Parts 
[assembly: System.Security.AllowPartial1yTrustedCal1ersO] 

The file RevenueWebPart.es contains a class named RevenueWebPart. We’ll transform this 
standard class into a Web Part for use with the Project Management site we’ve been working on. 

The first step is to add a reference to System.Web.DLL. This system assembly has types that are 
required to write ASPNET-style Web Parts. Next we modify the RevenueWebPart class so that 
it inherits from the WebPart class defined within the System.Web.UI.WebControls.WebParts 
namespace. Then, inside the RevenueWebPart class, we override the RenderContents method 
with a minimal “Hello, world” implementation. Here’s the code: 

using System; 
using System.web.ui; 
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using System.web.ui.webcontrots.webparts; 

namespace LitwarewebPartsLab { 

public class RevenuewebPart : webpart { 

protected override void RenderContents(HtmlTextwriter writer) { 
writer.write("Hello, world"); 

} 

} 

} 

A Web Part DLL must be placed in a location where the Windows SharePoint Services run 
time can find it. When you deploy a Web Part DLL, you have the option of putting it in the 
local \bin directory or the Global Assembly Cache (GAC). In this example, we’re going to 
compile the assembly DLL output for the LitwareWebPartsLab project directly to the \bin 
directory of the default Web site. To do this, we can modify the Output path for the Litware¬ 
webPartsLab project as shown in Figure 3-14. Now we can build the LitwareWebPartsLab 
project, and after compiling the project, we can verify that the assembly DLL has been created 
in the C:\InetPub\wwwroot\bin directory. 
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Figure 3-14 Setting the Output path in the project's properties window 


We also need to modify the Web.config file in the C:\InetPub\wwwroot directory by adding 
a SajeControl setting for the new Web Part. The setting uses the following format: 

<SafeControl Assembly="[assembly name]" Namespace="[namespace]" TypeName="*"/> 

In this example, the namespace is LitwareWebPartsLab and the four-part assembly format 
string looks like this: 


LitwarewebPartsLab, version=l.0.0.0, Culture=neutral, Pub!icKeyToken=d4e5777b!6a5749f 
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After compiling the Web Part DLL to the \bin directory and configuring it in the SajeControls 
list of the default Web site, we can add the Web Part to the Web Parts gallery of the top-level 
site. 

To do this, go to the Project Management site home page and click Site Settings on the Site 
Actions menu. Click the Web Parts link in the Galleries section to navigate to the Web Part 
Gallery page. Click the New button on the toolbar to open the page that allows you to add 
Web Parts to the gallery. Click the check box to the left of LitwareWebPartsLab.RevenueWeb- 
Part to select it, and then click the Populate Gallery button at the top of the page. 

You can now add the Web Part to any page in the current site collection. Navigate to the home 
page of the Project Management site, and then add the Web Part to a Web Part zone. Figure 
3-15 shows the home page with the Web Part added above the Litware slogan graphic. 



Figure 3-15 The top-level site with the custom Web Part 

The Revenue Web Part could be modified in a number of ways. For example, you could add 
code that provides for a persistent Boolean personalizable property named ShowTextAsBold. 
The property would give a user the ability to toggle bold text on or off. When the user has the 
property disabled, the Revenue Web Part renders its output using a standard font. When the 
property is enabled, the Revenue Web Part renders its output using a bold font with a larger 
size. If you’re in the mood, you could also change the color of the font. 

The Revenue Web Part could also be modified to generate some helpful business information 
from a SharePoint list. In the code you’ve seen to this point, the Web Part has been written as 
a standard ASP.NET Web Part that can run on any ASP.NET site. To enable the Web Part to 
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access data within a SharePoint list, you need to add Windows SharePoint Services-specific 
code to the DLL. 

First you need to add a reference to Microsojt.SharePoint.dll. Next, in the RenderContents 
method, you would write code to acquire a reference to the current site (an SPWeb object) and 
then obtain a reference to the Projects list (an SPList object). Next the code would enumerate 
through the list items one by one and add together the contract amounts to calculate a total. 
The sum of the contract amounts will be displayed as the total revenue. 

Code you could use to make modifications such as these is as follows: 

npublic class RevenuewebPart : webpart { 

protected bool _ShowTextAsBold = true; 

[ 

personalizableO, 
webBrowsable(true), 
webDlsplayName("Show Text As Bold"), 
webDescripfion("Enable to turn on bold font output") 

] 

public bool ShowTextAsBold { 

get{ return _ShowTextAsBold; } 
set{ value = _ShowTextAsBold; } 

} 

protected override void OnPreRenderfEventArgs e) 

{ 

this.Title = "Litware project Revenue"; 

} 

protected override void RenderContents(HtmlTextwriter writer) 

{ 

SPWeb ProjectManagementSite = SPContext.Current.web; 

SPList Projects = ProjectManagementSite.Lists["Projects"]; 
decimal Total Revenue = 0; 

foreach (SPListltem Project in Projects.Items) { 

TotalRevenue += Convert.ToDecimal(Project["Contract Amount"]); 

} 

if (_ShowTextAsBold) { 

writer.AddstyleAttribute(HtmlTextwriterstyle.Fontweight, "Bold"); 
writer.AddstyleAttribute(HtmlTextwriterstyle.Fontsize, "12pt"); 
writer.AddstyleAttribute(HtmlTextwriterstyle.Color, "Red"); 
writer.RenderBeginTag(HtmlTextwriterTag.Span); 

writer.write("Total Revenue: " + TotalRevenue.ToString("$#,###”)); 
writer.RenderEndTagO ; // </Div> 

} 

el se { 

writer.write("Total Revenue: " + TotalRevenue.ToString("$#,###")); 

} 

} 

} 




Chapter 4 

Organizing Lists and Documents 
with Site Columns and 
Content Types 


In this chapter: 

Content Types.57 

SiteColums .66 

Working with Site Columns and Content Types .67 


Large enterprises often encounter problems managing the volume of content they produce 
and store. Information workers create and rely on many different types of documents, but 
their organizations have no clear way to enforce standards with respect to the templates on 
which users base a document or the properties that are used to identify a document or classify 
the content it contains. In addition, an organization’s content management applications 
should be able to tie the list of actions that are available to users to the type of content or doc¬ 
ument. Finally, organizations need to store different types of documents in a central location 
rather than parcel out documents according to type or file format. 

This chapter provides an overview of two features in Microsoft Windows SharePoint Services 
that organizations can use to store and manage documents and other content: site columns 
and content types. The first sections of the chapter provide background about these features, 
and in the last part of the chapter well demonstrate some examples using a sample 
SharePoint site. Well look at content types first and then review site columns, which have 
much in common with content types. 

Content Types 

In Windows SharePoint Services 2.0, a list was defined by a single set of data requirements (or 
schema) that applied to each item in the list. Having a single set of requirements meant that a 
list item was tied to its location. All the items in that location had to adhere to the columns 
defined for the list or document library. In Windows SharePoint Services 3.0, lists can include 
multiple schemas, in the form of content types. Content types provide the means to encapsu¬ 
late a data schema and make it independent of a location on a SharePoint site. 
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Content types help users organize the documents and other material stored on a SharePoint 
site. For developers, a content type provides a way to define and use metadata to distinguish 
one type of list item from another. A content type is a collection of settings and metadata that 
is applied to a certain category of content. For example, a content type named Specifications 
might include columns that record metadata such as Project, Priority, Developer, and Test 
Lead. A content type named Contract might use columns such as Approver, Signed (Yes/No), 
and Amount. Even with these differences, specifications and contracts can be items in the 
same list or document library within a SharePoint site. 

Because content types are independent of a specific list or document library, a content type 
can be used in lists on multiple SharePoint sites, which enables the types of content stored in 
a site collection to be defined and managed more centrally. For example, the Specification 
content type could be applied to a number of relevant lists, even if specification documents 
are stored on multiple SharePoint sites, to ensure that an organization keeps track of the same 
metadata for all software and other project specifications. A content type can be extended by 
including in its definition settings such as a workflow or custom attributes that are applied to 
the items on a site. 


More Info For more information about using workflows on a SharePoint site, see 
Chapter 7, "Creating Workflows: The Missing Piece of Office Productivity." 


Content types can be defined through the Windows SharePoint Services user interface, by 
using the Windows SharePoint Services object model, or by deploying a feature that installs 
the content type based on an XML definition file. 


More Info For more information about features, see Chapter 5, "Working with Features in 
Windows SharePoint Services." 


Content Type Settings 

A content type can include the following information: 

■ Metadata, or properties, assigned to the type. These properties are represented by the 
columns added to the list or document library. 

■ A template on which to base documents of this type. 

■ Custom New, Edit, and Display forms to use with the content type. 

■ Event handlers. 

■ Workflows available for items of this content type. A workflow can be initiated automat¬ 
ically, based on a selected event or condition, or through a user’s action. 
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■ Retention policies. 

■ Information necessary for custom solutions associated with the content type. You can 
store this information in the content type as one or more XML documents. 

File Formats 

Content types are independent of file formats. In document libraries, a document template 
can be specified for a content type. Windows SharePoint Services uses this template when a 
user creates a document of this type. Users can still upload into the document library a docu¬ 
ment based on a different template or a file of a different file type. 

Suppose, for example, that you create a content type that will be applied to the documentation 
required for a project. The Project content type can be applied to any file format, including a 
Word document that contains project planning information, goals, risk assessments, and 
similar information; an Excel workbook that contains the project budget; a Microsoft Project 
document used for scheduling; and SharePoint list items that store the names and roles of 
team members, tasks, and the like. All these files and list items can be assigned the Project 
content type. 



Note You can assign content types to SharePoint items that do not have a file format at all, 
such as list items or folders. A content type created for documents can be applied only to doc¬ 
ument libraries; likewise, a content type created for list items can be applied only to lists. A 
content type created for folders can be applied to either document libraries or lists. 


Site and List Content Types 

A content type that you create at the site level is called a site content type. A site content type is 
a template that is independent of any specific list or library. Any child site can inherit a site 
content type. If a site content type is created at the root site of a site collection, any site in that 
site collection can inherit the site content type. 

Site content types are inherited by reference. When a child site inherits a site content type, 
Windows SharePoint Services includes a reference to the site content type locally in the child 
site. The site content type is then available to provision lists within the child site. 

When a site content type is added to a list, Windows SharePoint Services stores a local copy of 
the site content type in the list itself. This local instance, called a list content type, is applicable 
only to the list it is copied to. Because Windows SharePoint Services stores a copy of the site 
content type as a list content type in each list the content type is added to, changes to list- 
specific instances can be made without affecting the site content type itself. Changes to a list 
content type are limited to that list and do not affect the parent site content type or any other 
list content types that inherit from that site content type. 
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Creating Content Types Based on Other Content Types 

You can create content types based on other content types. Using this relationship, you can 
create general site content types that contain attributes for several different types of content 
and then derive more specific site content types from them. At the site level, you can create site 
content types based on other site content types. At the list level, you can create list content 
types based on site content types, provided that the site content type is within the scope of the 
site or list. 

You can edit the attributes of a site content type that you derive from another site content type 
by adding, altering, or removing columns; specifying different New, Edit, or Display forms; or 
specifying a different document template. 



Note The content type of an item is set explicitly by selecting the content type for that item. 
However, even items that haven't been assigned a specific content type must comply with the 
metadata requirements of the list or document library in which the items are located. The list 
schema functions as the default content type of the list itself. 


Figure 4-1 shows an example of the scope of content types created for a SharePoint site collec¬ 
tion. Site content types created at the root site of the collection, the Project Management site, 
are available for its direct child sites (North Division and South Division) and also for sites 
lower in the site hierarchy, such as North Region 1, North Region 2, and the Assignments list. 
Site content types created within the North Division site are available for the regional sites and 
the Assignments list, but these content types are not available in the South Division site 
because it is not a child of the North Division site. In addition, any content types created for 
the Assignments list are list content types and available only to that list. 

The base content type hierarchy included in Windows SharePoint Services corresponds to 
the types of lists that you can create. The base content type hierarchy includes types such as 
Document, Event, Issue, Contact, Task, Announcement, and so on. When you create a list, 
Windows SharePoint Services creates a list content type based on the appropriate base site 
content type. For example, when you create an announcement list, Windows SharePoint 
Services copies the Announcement content type locally to the list. 
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Figure 4-1 An example of content type scope 


Controlling Changes to Content Types 

You can prevent users from making changes to content types in two ways: specify a content 
type as read-only or define it as sealed. (There is no way, however, to prevent users from cre¬ 
ating content types based on a specific site content type.) 

Read-Only Content Types 

A read-only content type prevents users from making changes to the content type through the 
user interface in Windows SharePoint Services. The content type can still be altered program¬ 
matically, using the Windows SharePoint Services object model. Specifying that a content 
type is read-only also affects how changes made to the parent content type can be pushed 
down. You’ll learn more about updating content types and propagating changes in “Updating 
Content Types” on the next page. 

Sealed Content Types 

Defining a content type as sealed provides more control of the content type. Sealed content 
types cannot be changed through the Windows SharePoint Services user interface or the 
object model. To change a sealed content type, you need to change the definition of the 
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content type that is specified in the XML file used to provision the content type. Sealed con¬ 
tent types are not updated through push-down operations. 

Controlling Access to Content Types 

One way to control access to a content type is to specify that it be hidden. Hidden content 
types are not displayed in the Windows SharePoint Services user interface, so users are pre¬ 
vented from selecting or editing the content type. This approach is useful when defining site 
content types that will be used as the base for other content types that users can alter. Hidden 
content types can be accessed through the Windows SharePoint Services object model. 

Content types can also be added to a built-in content type group, named _hidden. This group 
is not displayed in the group lists from which users select content types to apply to lists or to 
use as the basis for other content types. Users also cannot select content types from this group 
to use as a parent for new content types. An administrator can choose to add a content type 
from this group to a list. 

Updating Content Types 

Each content type contains a reference to the site content type on which it is based. This ref¬ 
erence enables Windows SharePoint Services to push down changes that are made to a parent 
content type to site and list content types that are derived from it. Push-down operations are 
optional so that users who consume a content type can make their own customizations and so 
that an administrator can seal a content type to prevent others from making changes. 

When you choose to push down changes to a content type to all of its children, the operation 
does not overwrite the entire content type. The scope of what is overwritten depends 
on whether the changes and push-down operation are executed through the Windows 
SharePoint Services user interface or through the Windows SharePoint Services object model. 

If a push-down operation fails on a given child content type, Windows SharePoint Services 
continues propagating changes to other child content types. Windows SharePoint Services 
also returns a list of errors it encounters during a push-down operation. 



Note To create or manage a site content type on a site, you must have access rights to that 
site. If you do not have the appropriate access rights to a child site, push-down operations to 
content types contained in that child site will fail. 


Updating Content Types Through the User Interface 

When editing a site content type by using the Windows SharePoint Services user interface, all 
the settings contained on the content type settings page are overwritten during a push-down 
operation. The level of detail of the changes that can be pushed down is defined within the 
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following areas. Each time you make a change in an area, the entire area is overwritten when 
changes are propagated: 

■ Document template settings This area contains the following settings: 

□ Document template URL 

□ The actual document template file, if you selected an existing template on the 
Web site or uploaded a template file 

□ Read-only attribute 

■ New column settings This area involves adding a new column to the site content 
type. 

■ Column settings This area contains the following settings: 

□ Status 

□ Order 

□ Removing a column from the site content type 

Updating Content Types Through the Object Model 

The Windows SharePoint Services object model provides more control for propagating 
changes made to a content type to the children of that type. Changes to a site content type 
made through the object model affect the in-memory representation of the site content type, 
but Windows SharePoint Services doesn’t commit those changes to the site database until a 
program using the object model calls the Update method. 

The following code example adds two columns to a site content type named SalesPresenta- 
tion and then pushes down those changes to the content types based on SalesPresentation. 


SPWeb web = GetSPWebO; 

SPContentType myCT = web.ContentTypes["SalesPresentation"]; 
myCT.Fields.Add(Fieldl); 
myCT.Fields. Add(Field2); 

myCT.update(SPUpdateType.ListsAndTemplates); 

The following example changes the document template associated with the site content type. 
SPWeb web = GetSPWebO; 

SPContentType myCT = web.ContentTypes["SalesPresentation"]; 
myCT.DocumentTemplate = "SpecTemplate.doc"; 
myCT.update(SPUpdateType.ListsAndTemplates); 

Updating Custom Information in Content Types 

You can push down custom settings defined for a content type in an XML document by using 
the Windows SharePoint Services object model. Each content type has an XML document col¬ 
lection that a third-party solution can use to store custom settings information. Specific XML 
documents can be overwritten when changes to a content type are propagated. Windows 
SharePoint Services does not attempt to determine whether an XML document is currently 
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being used or is needed for a process before overwriting it. XML documents can also be 
deleted entirely as part of a push-down operation. 

Considerations for Pushing Down Changes 

The following list summarizes some considerations to keep in mind for push-down opera¬ 
tions: 


■ Propagating changes to a site content type will overwrite modifications that have been 
made to one or more child content types if the changes to the child content type fall 
within the scope of the push-down operation. For example, suppose you made a change 
to a column in a child content type. If you make changes to that column in the parent 
content type (or delete the column altogether) and then push down the changes, 
Windows SharePoint Services overwrites the changes that you made to that column in 
the child content type. 

■ Each push-down operation propagates only the changes made to the parent content 
type at that time. If you do not push down the changes at the time you make them, you 
cannot easily push down those changes later. In most cases, you would need to reinstate 
your previous changes, make the changes again, and then push down that set of 
changes. For example, suppose that you deleted a column from a parent content type 
but did not push down this change when you deleted the column. A push-down opera¬ 
tion that occurs later would not delete that column from child content types. To remove 
the column from the child content types through a push-down operation, you would 
need to add the column to the parent content type, delete it again, and then push down 
the change. 

■ If you push down changes that are no longer applicable to a child content type, those 
changes are ignored. For example, if you push down column settings changes for a 
column that has been deleted from a child content type, those changes are ignored. 
Windows SharePoint Services does not add the column to the child content type. 

■ If you push down changes to the column order of a content type, and the child content 
type has more or fewer columns than its parent, Windows SharePoint Services does the 
following: 

□ If a column isn’t included in the child content type, the column is skipped in the 
column order of the child content type. 

□ If a child content type includes a column that isn’t included in the parent, 
Windows SharePoint Services places that column at the end of the column order. 
If a child content type includes more than one column that the parent does not 
have, these columns are placed at the end of the column order and sorted by their 
order number prior to the push-down operation. 
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■ If you attempt to perform a push-down operation on a child content type that is marked 
as read-only, the push-down operation fails unless you set the template to be read-write 
as part of the push-down operation. 

■ If a child content type is defined as sealed, the push-down operation fails on that con¬ 
tent type. 

Note You cannot delete a site content type if it is being used as the basis for other site or list 

-Gen4en44ypeSv-Y©u-4mj5t4«¥t-t«m®ve4his-e©nteR44ype-fem^iiste4Jsio^- 

site content types. Windows SharePoint Services does not consider items sent to the Recycle 
Bin when making this determination. If those items are restored after their content type has 
been deleted from the list, those items are assigned the default content type for that list. 


Extending Content Types 

Developers can extend the definition and functions of content types by using XML docu¬ 
ments. These documents can conform to any given schema; they only need to be valid XML. 
XML documents included in a site content type are also copied to any child types. If you make 
a change to an XML document and then perform a push-down operation, the entire XML doc¬ 
ument is overwritten in any child content types. 

The XML file that defines a content type must adhere to the content type definition schema. 
The following XML shows the structure of the content type schema: 

<Elements> 

xml ns:"http://schemas.microsoft.com/sharepoint/” 

<ContentTypes> 

<ContentType> 

ID as CTID, required 
Name as string 
Group as string 
Sealed as boolean 
version as integer 
Readonly as boolean 
Hidden as boolean 
Description as string 
<FieldRefs> 

<FieldRef> 

ID as GUID, required 
Name as string 
DisplayName as string 
Required as boolean 
Hidden as boolean 
Sealed as boolean 
Readonly as boolean 
ReadOnlyClient as boolean 
<RemoveFieldRef> 

ID as GUID, required 
Name as string 
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<DocumentTemplate> 

TargetName as path 
<XMLDocuments> 

<XMLDocument> 

NamespaceURl as string, required 

To see an application of this schema, here is the XML that defines the Document content type 
in Windows SharePoint Services: 


<?xml version="1.0" encoding="utf-8" ?> 

<!— _1cid="1033" _version="12.0.3008" _dal="l" —> 

<Elements xmlns="http://schemas.microsoft.com/sharepoint/"> 

<ContentType id="Ox 0101" Name="$Resources:Document" 

Group="SResources:Base_Content_Types" Sealed="TRUE" version="0"> 
<FieldRefs> 

<RemoveFieldRef ID="{67df98f4-9dec-48ff-a553-29bece9c5bf4}" 
Name="Attachments" /> <!— Attachments —> 

<FieldRef ID=”{5f47e085-2150-41dc-b661-442f3027f552}" 
Name="SelectFilename" /> <!— SelectFilename —> 

<FieldRef lD="{8c06beca-0777-48f7-91c7-6da68bc07b69}" Name="Created" 

Hidden="TRUE" /> <!— Created --> 

</FieldRefs> 

<xmlDocuments> 

<xmlDocument NamespaceURl= 

"http://schemas.microsoft.com/sharepoint/v3/contenttype/forms"> 
<FormTemplates> 

<Display>DocumentLibraryForm</Display> 

<Edit>DocumentLibraryForm</Edit> 

<New>DocumentLibraryForm</New> 

</FormTemplates> 

</xmlDocument> 

</xmlDocuments> 

</ContentType> 

</Elements> 


Site Columns 

A site column is a column definition that can be used in multiple lists on multiple SharePoint 
sites. Site columns have much in common with content types. For example, like a content 
type, a site column can help keep metadata about an item consistent across sites and lists. 
Also like site content types, you define a site column at the site level, independent of any 
actual list or content type, and child sites inherit site columns by reference. When you add a 
site column to a list, the site column is copied locally to the list as a list column. 

Site columns are scoped in the same manner as site content types. The site column is available 
to the site on which it is created and on any child sites. At the site level, the site column collec¬ 
tion contains definitions for or references to the definitions for each site column available on 
the site, whether or not is has been added to a content type or list. 
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Site Column Properties 

A site column has several properties that define it, including its name and its data type. A site 
column is also a member of a column group, which is a user-defined group that organizes col¬ 
umns into categories. 

A site column’s name must be unique among all column groups in the scope at which you cre¬ 
ate the site column. A site column can be defined with one of the data types supported by 
Windows SharePoint Services, including Single Line of Text, Multiple Lines of Text, Number, 
Date and Time, Lookup, Currency, and others. 

When you add a site column to a specific list or content type, you can set properties for the 
column to define its behavior within that list or content type. For example, you can specify 
whether the column information is required, whether the column is read-only, and whether 
the column is hidden. 

Each element manifest that defines a site column must follow the column definition schema. 
The column definition schema for Windows SharePoint Services 3.0 builds on the schema 
used in Windows SharePoint Services 2.0, retaining all its elements. The following XML 
shows the schema: 

<et ements> 

xm1ns="http://schemas.microsoft.com/sharepoi nt/” 

<fietds> 

<fietd> 

ID as guid, required 
Group as string, required 
Name as string, required 
DisptayName as string, required 
Type as fietdtype, required 
Seated, as boolean 
ReadyOnly, as boolean 
Hidden, as boolean 
RowOrdinal, as integer 

Working with Site Columns and Content Types 

In the following sections, you’ll see examples of how content types and site columns are used 
to manage and store information. First, well create a site column definition on a top-level site 
(the Project Management site created in the previous chapter) that performs a lookup in the 
Projects list. Well use that site column to define a column in a list on a child site within the 
same site collection. Next well create several content types. As mentioned earlier, content 
types provide an additional layer of organization and access to the content that is stored in a 
document library, and offer a mechanism by which users can store documents in a document 
library in a more structured way. 
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Creating a Site Column for Project Lookups 

The site column we create in this section is used to look up items in a list. To start, on the top- 
level site, click Site Settings on the Site Actions menu to open the Site Settings page. Under 
Galleries, click Site Columns, and then click Create on the Site Column Gallery page, which 
lists the built-in site columns and their types. When you click Create, the New Column page, 
shown in Figure 4-2, opens. 
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Figure 4-2 The New Column page 


Well name the site column Project and specify that its type is Lookup. We also add the col¬ 
umn to a new group, named Litware. In the Additional Column Settings section, we can add 
a brief description and modify the site column so that it requires information. We assign the 
Projects list as the source of information for the lookup column and designate the Project col¬ 
umn as the column to be used in the lookup. When we’ve finished filling out the New Column 
page, the Group and the Additional Column Settings sections include the information shown 
in Figure 4-3. 
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We can now use the Project site column in a list. We create a list that uses this site column on 
the North Division child site created in the previous chapter. The list will be used for tracking 
consultant time sheet information. This scenario demonstrates how a site column can easily 
enable lookups across sites within a site collection. 

On the North Division site, click Create on the Site Actions menu to open the Create page. In 
the Custom List area, click Custom List, which takes you to a page that you use to name the 
new list. Name the list Timesheets. 

When the Timesheets list is created, its Allitems.aspx page opens. On this page, click List Set¬ 
tings on the Settings menu to open the Customize Timesheets page. Click Versioning Settings 
in the General Settings section. On the Versioning Settings page, modify the list by selecting 
Yes for the option Create A Version Each Time You Edit An Item In This List? With this 
option, you can track changes made to time sheet items in the list by time and user. 


The next step is to define columns for the Timesheets list, which are listed and described in 
the table on the next page. 
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Column Name 

Type 

Notes 

TimesheetID 

Single Line of Text 

Renamed the Title column to TimesheetID. 

Consultant 

Choice 

To simplify this example, this is a choice column with 
three choices for the consultant: Britta Simon, John 
Rodman, and Mike Fitzmaurice. 

Project 

Lookup 

This column should be based on the Project site col¬ 
umn created earlier in this example. It was created by 
clicking the link Add From Existing Site Columns. 

Submitted On 

Date and Time 

This column is formatted to show the date only. It is 
also a required column. The default value is the current 
date. 

Hours 

Number 

This is a required column. The minimum value is set to 

1 hour and maximum to 24 hours. The maximum rep¬ 
resents the fact that each time sheet item will account 
for one specific day. 

Hourly Rate 

Currency 

This is a required column. 

Created By 

Person or Group 

This column is automatically created when you create 
a new list. 

Modified By 

Person or Group 

This column is automatically created when you create 
a new list. 


Figure 4-4 shows the Timesheets list with some test data entered. You can see that the Project 
column has performed lookups using project names in the Projects list from the parent 
Project Management site. 



Figure 4-4 The custom Timesheets list includes the site column named Project. 
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Creating Custom Content Types 

In this section, you’ll see how to implement custom content types and use them within a 
document library. First, we’ll create a content type named LitwareDocument. This content 
type serves as a base content type. We’ll also create two content types, LitwareProposal and 
LitwarePresentation, that derive from LitwareDocument. 

Start on the Project Management site’s home page by clicking Site Settings on the Site Actions 
menu. On the Site Settings page, under Galleries, click Site Content Types to open the Site 
Content Type Gallery page, shown in Figure 4-5. Like the site column gallery, the site content 
gallery lists the standard document, folder, list, and other content types that Windows 
SharePoint Services provides. 
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Figure 4-5 The Site Content Type Gallery page 


Next, click Create to open the page used to create a content type. To create the LitwareDocu¬ 
ment content type, fill in the page with the information shown in Figure 4-6. Notice that the 
content type was added to a new group, named Litware. 
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Figure 4-6 The LitwareDocument content type serves as a base content type. 


To continue defining the LitwareDocument content type, we added three columns from 
the set of custom and built-in site columns: Author, Project, and Append-Only Comments. 
The Author column and the Append-Only Comments columns are provided as standard Win¬ 
dows SharePoint Services site columns. The Project column is the custom column created in 
the previous example. The Add Columns page is shown in Figure 4-7. 



Note To get this example to work in beta 1, the Project column had to be configured as an 
optional column. 


Next we created two derived content types: LitwareProposal and LitwarePresentation. These 
content types inherit from LitwareDocument, which means that they automatically contain 
the columns defined for the base content type. We can extend the derived content types by 
associating a document template with each of them. 

Figure 4-8 shows the information used to define the content type named LitwareProposal. 
The settings for LitwarePresentation are essentially the same. As you can see, the derived 
content type contains the same columns that were defined in the base content type, 
LitwareDocument. 
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Figure 4-7 The LitwareDocument content type includes built-in and custom site columns. 



Figure 4-8 The LitwareProposal content type is derived from LitwareDocument. 
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By clicking the Advanced Settings link, we open a page that’s used to upload a document tem¬ 
plate for this content type. In this example, the template file for proposals is named Litware- 
ProposalTemplate.dotx, as you can see in Figure 4-9. 



Figure 4-9 The LitwareProposal content type is associated with a particular document template. 

After completing these steps, there are two content types that can be used within the Project 
Documents document library. 

Before this set of content types can be used, we need to configure the Project Documents doc¬ 
ument library so that it allows multiple content types. We do this by opening the Document 
Library Settings page and then clicking the Advanced Settings link. Figure 4-10 shows the Doc¬ 
ument Library Advanced Settings page and the option that allows for multiple content types. 

We also use the Document Library Settings page to add the content types LitwareProposal 
and LitwarePresentation to the document library. In the Content Types section of the page, 
click Add From Existing Site Content Types, and then add LitwareProposal and Litware¬ 
Presentation. 

Now we can go back and examine the files that are already in the Project Documents docu¬ 
ment library by choosing Edit Properties in the drop-down menu for each individual docu¬ 
ment. This command opens a page that allows you to change the content type for each 
document. When we’ve finished with the test data, there should be no documents still 
assigned to the standard content type named Document. Figure 4-11 shows the properties for 
a sales presentation with the LitwarePresentation content type specified. Notice that the con¬ 
tent type columns—Author, Project, and Append-Only Comments—are included in the docu¬ 
ment’s properties. 
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Figure 4-10 Document libraries need to be configured to allow multiple content types. 



Figure 4-11 Document properties now include the columns defined for the LitwarePresentation 
content type. 

You can test whether a particular content type has been specified for each file in a document 
library by opening the Document Library Settings page for the document library and 
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removing the original content type named Document. You will not be able to remove the Doc¬ 
ument content type if one or more documents in the document library still are assigned to this 
content type. 

Users of the Project Management site can now use the New menu in the Project Documents 
document library to create a Litware proposal or a Litware presentation based on the tem¬ 
plates assigned to these content types, as shown in Figure 4-12. 
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Figure 4-12 The New menu includes commands for creating documents of particular types 
using a specific template. 



Chapter 5 

Working with Features in 
Windows SharePoint Services 


In this chapter: 

Implementing Features .78 

Feature Elements .78 

Element Scope.79 

Activation Dependencies and Scope.79 

The Structure of Feature.xml.80 

Features and the Windows SharePoint Services Object Model.82 

Designing Windows SharePoint Services Applications Using Features .84 


Microsoft Windows SharePoint Services features are collections of logically related items and 
operations that can be added to and used repeatedly across site definitions. Features are a way 
to enhance the modular provisioning of SharePoint sites and help lessen the work required to 
make simple site customizations. For example, features eliminate the need to copy large 
blocks of code to change simple functionality. They reduce versioning and inconsistency 
issues that can arise among front-end Web servers, and they make activating or deactivating 
functionality in the course of a SharePoint deployment easier. An administrator, for example, 
can transform the template or definition of a site by toggling a particular feature on or off in 
the Windows SharePoint Services user interface. 

Features provide the following capabilities : 

■ Scoping semantics for determining where custom code runs 

■ Pluggable behavior for installing or uninstalling features within a deployment 

■ Pluggable behavior for activating or deactivating features at a given scope 

■ A scoped property bag for storing data required by a feature within its scope 

■ Versioning and upgrade semantics that enhance code consistency and safeguard cus¬ 
tom code within a deployment 

■ A framework for distributed deployment of SharePoint solutions 
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This chapter touches on the basics of working with Windows SharePoint Services features, 
including how to implement a feature, the structure of the XML file that defines a feature, and 
the Windows SharePoint Services classes that are used to work with features programmati¬ 
cally. The last main section of the chapter demonstrates how to create and implement a sim¬ 
ple feature on a SharePoint site. 

Implementing Features 

To implement a feature, you need to add a subfolder that contains the feature’s definition to 
the Features setup directory at the following location: 

\Program Files\Common Files\Microsoft Shared\web server extensions\ 
12\TEMPLATE\FEATURES 

The subfolder for a feature includes a file named Feature.xml, which defines the base proper¬ 
ties of the feature and lists elements that are bound to the feature, such as XML files that con¬ 
tain element manifests and other supporting files. The folder for a feature might contain only 
the Feature.xml file, or it might contain Feature.xml and any number of supporting element 
files, including other XML files or .aspx, .htm, .xsn, .resx, .dll, or other file types. 

After creating the feature’s folder, you can install and activate the feature through the Win¬ 
dows SharePoint Services user interface, command-line operations using stsadm.exe, or the 
Windows SharePoint Services object model. (You’ll see examples of batch files that use 
stsadm.exe later in this chapter.) Installing a feature makes the feature definition and its ele¬ 
ments known throughout a server farm. Activating a feature makes the feature available at a 
particular scope. 

Feature Elements 

As mentioned previously, a feature includes the Feature.xml file and any number of files 
describing elements of the feature. The Feature element is used in Feature.xml to define a fea¬ 
ture and to specify the location of assemblies, files, dependencies, or properties that support 
the feature. The Feature element can also be used in an Onet.xml file to specify that a feature 
be included within a site definition. 

A Feature.xml file usually points to one or more XML files whose top-level Elements tag con¬ 
tains definitions of elements that support the feature. Elements in Windows SharePoint Ser¬ 
vices 3.0 correspond to what were discrete nodes in the Onet.xml or Schema.xml file in the 
previous version. 

A feature can include several types of elements, such as a custom menu item, an event han¬ 
dler, a content type, a list instance, and so on. The collective operation of these elements and 
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their relationship defines the functionality of a feature. For example, a feature named “My 
Favorite Items” might provide its functionality by including the following elements: 

■ A custom list that stores each user’s favorite items. The list is created as a single hidden 
list per workspace when the feature is enabled. 

■ A custom menu item named Add To Favorites that is attached to all lists. 

■ A Web Part that implements usage and link tracking to display the user’s top 10 favor¬ 
ites as the first items in the list. 

Element Scope 

Features can be scoped at the level of a site, site collection, Web application (virtual server), or 
server farm. A particular feature can be activated for a single scope. The scope of a feature is 
determined by the value of the Scope attribute of the Feature element. 

■ Site and site collection scope A site feature is scoped at the individual site level. A site 
collection feature contains items that apply to the site collection as a whole (Web Parts 
or item profiles that apply to the site collection, for example) in addition to items that 
can be activated per site. Elements with a site or site collection scope include list defini¬ 
tions (templates, views, and instances), modules (file sets), and item content type 
behaviors (for example, per-item custom menu options and per-item events). 

■ Web application scope A feature scoped for a Web application, or virtual server, can 
be activated or deactivated and can contain the elements for virtual server assemblies 
and virtual server administrative links. 

■ Server farm scope A farm feature is scoped for an entire server farm and, unlike a fea¬ 
ture with site or site collection scope, is always activated by default in the farm. A farm 
feature contains a number of elements that are required for implementing applications 
and logic anywhere within a deployment of SharePoint. A farm feature can contain links 
to _layouts pages and files, _admin pages, and other elements. 

Activation Dependencies and Scope 

A feature can be defined so that it is dependent on another feature or features for activation. 
Activation dependencies can be expressed for features of the same scope, or a feature at a par¬ 
ticular scope can be dependent on a feature at a different scope (a cross-scope activation 
dependency). For example, a feature at the site level can be dependent on a feature that is 
scoped for the site’s site collection. Cross-scope activation dependencies cannot be formed if 
the dependent feature has a more restrictive scope. In other words, a feature scoped for a site 
collection cannot have an activation dependency on a feature scoped at the site level. 
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A feature can have an activation dependency on either hidden or visible features. (A hidden 
feature is determined by the setting of the Hidden attribute of the Feature element.) Hidden 
features themselves, however, cannot have any activation dependencies. 



Note Windows SharePoint Services 3.0 deactivates a dependent hidden feature if the last 
visible feature at the same scope that has an activation dependency on the hidden feature is 
deactivated. 


Scope and Feature Globalization 

Two types of resources can be implemented in features for support files: 

■ Local resources that are stored in a subdirectory within the Features folder in the 
\TEMPLATE\FEATURES directory. 

■ Shared application feature and site definition resources that are stored in \web 
server extensions \12\Resources and are designed to be used across features and 
site definitions. 

The Localeld attribute of the Feature element specifies the language of the feature. This 
attribute can be set to 0, which makes the feature available to all languages and cultures. 
The developer of a feature can declare a feature to be culture-neutral, even if the feature 
contains potentially localizable resources, which will be displayed in all languages. 

The set of language support files plus the default language of the feature constitute the 
set of available languages for a feature. A feature scoped at the farm or Web application 
level does not activate if the feature does not support the language of the administrative 
user interface. A feature scoped at the site collection level always activates because a site 
collection is assumed to be inherently multilingual. A feature with a site scope is not 
available for a site if it does not support the language of the site. 


The Structure of Feature.xml 

In the Feature.xml file, the Feature element defines a feature and specifies the location of 
assemblies, files, dependencies, or properties that support the feature. A Feature.xml file can 
contain the following elements: 

Feature 

ActivationDependenci es 
ActivationDependency 
ElementManifests 
ElementFile 
ElementManifest 
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Th t ActivationDependencies element specifies a list of the features on which this feature 
depends for activation. The ElementManifests element specifies a list of element container files 
that include definitions for the operations that make up the feature. 

The following table lists and describes the attributes for these elements. 


Name 

Data Type 

Description 

Feature Attributes 

Id 

Guid 

The unique identifier for the feature. 

Title 

Text 

Returns the title of the feature; limited to 255 
characters. 

DefaultResourceFile 

Text 

Optional. By default, if a developer specifies a resource 


in the Feature.xml file, Windows SharePoint Services 
looks in FeatureName\Resources\Resources.Cul- 


ture.resx. However, through DefaultResourceFile, you 
can specify an alternative file from which to grab 
resources. 


Description 

Text 

Optional. Returns a description of the feature's 
function. 

Version 

Version 

Specifies a System. Version-compliant representation 
of the version of a feature. This value can be up to 
four numbers, delimited by decimals, that represent a 
version. 

ReceiverAssembly 

Text 

Optional. If this attribute is set along with Receiver- 
Class, it specifies the assembly from which to load a 
receiver to handle feature events. 

ReceiverClass 

Text 

Optional. If this attribute is set along with Receiver- 
Assembly, it specifies the class that implements the 
feature event processor. 

ActivationDependency Attributes 

Featureld 

Guid 

The ID of the feature that a dependency refers to. 

Title 

Text 

Optional. Title of the feature on which this feature is 
dependent. This field is usually localized. 

Description 

Text 

Optional. Description of the feature on which this fea¬ 
ture is dependent. This field is usually localized. 

Url 

Text 

Optional. A URL that contains more information about 
the feature in question. This field is usually localized. 

ElementFile Attributes 

Location 

Text 

Specifies the relative file path to the root element 
manifest file. 

ElementManifest Attributes 

Location 

Text 

Specifies the relative file path to the root element 
manifest file. 
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The following example shows a Feature.xml file that specifies installation dependencies, spe¬ 
cial fields, and relative paths to element definition files. 

<Feature 

ld="1111111-11111-11111-11111" 

Title="Location Services" 

Description="This feature contains lists and parts that let you link 
location data to your customer lists." 

Scope="web”> 

<lnstal1ationDependencies> 

<lnstal1ationDependency 

Id="FEEDBADA-11111-111111" 

Title="Portal Search" 

Description="This feature contains portal search functionality" 
url="http://www.microsoft.com/sharepoint"> 

</lnstal1ationDependency> 

</lnstal1ationDependencies> 

<propertySchema> 

<Fields> 

<Field 

Type=”Text" 

Name="ProjectName" 

DisplayName="Project Name"> 

</Field> 

</Fields> 

</propertySchema> 

<ElementManifests> 

<ElementManifest Location="Location\LocationPart.xml”/> 

<ElementManifest Location="CustomerLocation\CustomerLocationList.xml”/> 

<ElementFi1e Location="test.aspx"/> 

</ElementManifests> 

</Feature> 


Features and the Windows SharePoint Services 
Object Model 

Windows SharePoint Services provides an object model that can be used to determine the list 
of installed features within a given scope and for controlling whether features are enabled at 
the farm and site levels. The following sections summarize the classes used in working with 
features. 

Feature Classes 

The following are the main classes you use to work with SharePoint features programmatically: 

■ SPFeature (SPFeatureCollection ). This class returns an object that represents the state of 
a feature at its corresponding level. The presence of a feature in a collection at the virtual 
server, site collection, or site level scope means that the feature is activated. The absence 
of an SPFeature object indicates that the object is not added. The SPFeature class is 
included in the Microsoft.SharePoint namespace. 
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■ SPFeatureProperty (SPFeaturePropertyCollection ). Objects of this class represent a single 
feature property. The SPFeatureProperty class is included in the Microsoft.SharePoint 
namespace. 

■ SPFeatureScope. This class provides an enumeration of the possible scopes that can be 
specified for a feature, including Farm, WssWebApplication, Site, and Web. The SPFeature¬ 
Scope class is included in the Microsoft. SharePoint namespace. 

■ SPFeatureDefinition (SPFeatureDefinitionCollection). This class contains the base defini¬ 
tion of a feature, including its name, type, and the version of the feature. Also, you can 
store properties about the feature globally per feature. For example, a feature could be 
associated with a central administrative page for setting configurations for a feature. The 
SPFeatureDefinition class is included in the Microsoft.SharePoint.Administration 
namespace. 

■ SPFlementDefinition (SPElementDefinitionCollection ). This class represents an element to 
be provisioned when the feature is activated or used. The SPElementDefinition class is 
included in the Microsoft.SharePoint.Administration namespace. 

Accessing Feature Collections 

You can get the collection of features for a Web application, farm, site collection, or site by 
using one of the following properties to access the collection: 

■ Microsoft.SharePoint.Administration.SPWssWebApplication.Features returns a list of 
features activated at the virtual server level for the Windows SharePoint Services Web 
application. 

■ M icrosoft.SharePoint.Administration.SPWssService.Features returns the administrative fea¬ 
tures that have been activated at the server farm scope. 

■ Microsoft.SharePoint.Administration.SPFarm.FeatureDefinitions returns the list of all 
installed features in the server farm. 

■ Microsoft.SharePoint.SPSite.Features returns the list of features for the site collection. 

■ M icrosoft.SharePoint.SPWeb.Features returns the list of activated features for a site. 

The following example demonstrates how to use several of these classes and properties to dis¬ 
play the list of names and the GUIDs of the features that are activated on a specified site: 

SPSite siteConection = SPControi .GetContextSite(Context) ; 
spweb site = siteConection,Anwebs["Site"]; 

SPFeatureCoHection siteFeatures = site.Features; 

System.Globalization.Cuitureinfo cuitureinfo = new System.Globalization.Cuiturelnfo(1033); 

foreach (SPFeature siteFeature in siteFeatures) 

{ 

Response.write("Titie: " + siteFeature.Definition.GetTitiefcuiturelnfo) + 

"<br>id: " + siteFeature.Definitionld.ToStringO + ”<br><br>") ; 

} 
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The next example uses information returned through the previous example to add a feature 
to a subsite: 

SPWeb subsite = site.websf""]; 

System.Guid guid = new System.Guid("6e005f62-f8b2-4073-a673-c035c9129946"); 
subsiteFeatures.Add(guid); 

Features and Events 

Windows SharePoint Services also provides classes for responding to feature events. These 
classes allow you to trap and respond to an event that occurs when a feature is installed in a 
server farm, added to a new virtual server, or removed. Such an event is a post event , meaning 
that it occurs after the respective behavior has been committed and the feature definition has 
been created in the collection of feature definitions for the farm. You cannot cancel the instal¬ 
lation or removal of a feature through a feature event. 

■ SPFeatureReceiver is the base abstract class that can be overridden to trap the activation, 
deactivation, installation, or removal of a feature. Each of these events is a post event. 
The SPFeatureReceiver class is included in the Microsoft.SharePoint namespace. 

■ The SPFeatureReceiverProperties class provides access to event properties such as the fea¬ 
ture instance that has been created, the feature definition, or the parent object of the 
feature (for example, an SPWeb object). The SPFeatureReceiverProperties class is included 
in the Microsoft.SharePoint namespace. 

Designing Windows SharePoint Services Applications 
Using Features 

The following sections present examples of how to work with features on a SharePoint site. 
Well look at features from the end-user perspective, to see how a feature is activated or deac¬ 
tivated, and then well look at the XML file structure for a feature and at a batch file that can 
be used to install and activate a custom feature using stsadmin.exe commands. Well com¬ 
plete the set of examples by creating and testing a custom feature using XML files and 
Microsoft Visual Studio 2005. 

Activating and Deactivating Features 

Ligure 5-1 shows the Create page for a new Windows SharePoint Services site at the root of 
the default Web site. This top-level site is based on the Blank Site template. As you can see, the 
Document Libraries section lists four types of libraries that can be created for the site: Wiki 
Page Library, Document Library, Data Connection Library, and Lorm Library. Slide Library is 
not among the items in this list. It first needs to be activated as a feature before one can be cre¬ 
ated for this site. 
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Figure 5-1 The Create page shows the types of document libraries available for this site. 

Here are the steps for activating a feature for a site collection: 

1. On the home page, click Site Settings on the Site Actions menu. 

2. On the Site Settings page, in the Site Administration section, click Site Features to open 
the Site Features page for the current site. (See Figure 5-2 on the next page.) You can use 
this page to examine the set of installed features available at the site level, including 
those that are activated and deactivated for the current site. Also, you can determine 
which features are automatically activated for the site template you used. 

3. Locate the feature you want to activate (Slide Library, for example), and then click Acti¬ 
vate. Click Deactivate to deactivate a feature. 


Note After you have activated a feature, return to the site's Create page (click Create on the 
Site Actions menu), and you should be able to confirm that the feature you activated now 
appears. 
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Figure 5-2 Use the Site Features page to activate or deactivate a feature through the Windows 
SharePoint Services user interface. 

Working with a Custom Feature 

Next we’ll look at some of the files used to define a feature and at a batch file that can be used 
to install and activate a feature that you might create. The feature well examine is a custom list 
type named LitwareTimesheets. This feature has been designed to create a list instance and 
add some initial data items to the list. 

Figure 5-3 shows the Feature.xml file, which is the feature manifest. As you can see, this file 
gives the feature its name and identifying GUID and defines its scope. This feature is scoped 
at the site level because its scope has the value "Web". You can also see that an ElementManifest 
element points to the location of a file named Timesheets.xml, which contains the data that 
will be included in the list once the feature is installed. 
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Figure 5-3 The feature manifest file, Feature.xml 


The following XML, from the schema.xml file, defines the list’s fields. This file also defines list 
views and other information. 

<?xmi version="1.0" encoding="utf-8"?> 

<List xm1ns:ows="Microsoft SharePoint" 

Name="Timesheets" 

Titie="Timesheet List" 

Direction="0" 

Uri="Lists/Timesheets" 

BaseType="0" 

> 

<MetaData> 

<Fieids> 

<Fieid Name="Titie" FromBaseType="TRUE" Type="Text" 

DispiayName="TimesheetlD" Required=" false" 

MaxLength="24" ID="{fa564e0f-0c70-4ab9-b863- 
0177e6ddd247}" version="l" StaticName="Titie" 

SourcelD="http://schemas.microsoft.com/sharepoint/v3" 

CoiName="nvarcharl" RowOrdinai="0"/> 

<Fieid Type="Choice" DispiayName="Consu1tant" 

Required="TRUE" MaxLength="50" lD="{96fe5f63-bd85-4f87- 
b423-5437e803b242}" SourcelD="{e9b34e79-429b-42a4-bc6a- 
8b766aa59987}" StaticName="Consuitant" 

Name="Consuitant" CoiName="nvarchar3" RowOrdinai="0”> 

<Defau1t>Britta Simon</Defauit> 

<CHOICES> 

<CHOlCE>Britta Simon</CHOlCE> 

<CHOlCE>John Rodman</CHOICE> 

<CHOlCE>Mike Fitzmaurice</CHOlCE> 

</CHOICES> 


</Fieid> 
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<Field Type="Choice" DisplayName="Project" Required="TRUE" 

Maxl_ength="50" lD="{el8a2fdc-c40a-4e33-9e84- 
10a5df587da4}" SourcelD="{e9b34e79-429b-42a4-bc6a- 
8b766aa59987}" StaticName="Project" Name="Project" 

CotName="nvarchar4" RowOrdfnal="0"> 

<Default>FI-23-123</Default> 

<CHOICES> 

<CHOICE>FI-2 3-123</CHOICE> 

<CHOICE>MR-2 3-12 3</choice> 

<choice>pr-io-232</choice> 

</CH0ICES> 

</Field> 

<Field Type="DateTime" DisplayName="Submitted On" 

Required="TRUE" Format="DateOnly" lD="{4676b294-OcOO- 
476a-8693-6012028ececf}" SourcelD="{e9b34e79-429b-42a4- 
bc6a-8b766aa59987}" StaticName="Submitted_x0020_On" 

Name="Submitted_x0020_On" ColName="datetimel" 

RowOrdinal="0"> 

<Default>[today]</Default> 

<DefaultFormulavalue>2005-12- 

30T00:00:00z</DefaultFormulavalue> 

</Field> 

<Field Type="Number" DisplayName="Hours" Required="TRUE" 

Min="l" Max="24" Decimals="0" lD="{98fbe207-eedb-4903- 
bbb9-d84016dfa0d0}" SourcelD="{e9b34e79-429b-42a4-bc6a- 
8b766aa59987}" StaticName="Hours" Name="Hours" 

ColName="floatl" RowOrdinal="0"/> 

<Field Type="Currency" DisplayName="Hourly Rate" 

Required="TRUE” Min="40" Max="225" lcid="1033" 

ID="{d77c5eal-6646-4bl8-90e4-16a23fb8dcd7}" 

SourcelD="{e9b34e79-429b-42a4-bc6a-8b766aa59987}" 

StaticName="Hourly_x0020_Rate" Name="Hourly_x0020_Rate" 

ColName="float2" RowOrdinal="0"/> 

</Fields> 

And here is the XML that shows list properties and some of the data used to populate the list, 
from the Timesheets.xml file: 

<?xml version="1.0" encoding="utf-8" ?> 

<Elements xmlns="http://schemas.microsoft.com/sharepoint/"> 

<ListTemplate 

Name="Timesheet" 

Type="10201" 

BaseType="0" 

OnQuickLaunch="TRUE" 

SecurityBits="ll" 

DisplayName="Timesheets" 

Description="Litware Time Sheet List Type" 
lmage=”/_layouts/images/CHNGCOL.GlF"/> 

<Listlnstance 

ld="Timesheets" 

Description="Litware Time Sheet List instance" 

TempiateType="10201" 

Title="Timesheets" 
url="Timesheets" 

> 
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<Data> 

<ROWS> 

<ROW> 

<Field Name="TimesheetlD">Britta Simon FI-23-123 
l/2/2006</Field> 

<Field Name="Consuitant">Britta Simon</Field> 

<Field Name="Project">Fl-23-123</Field> 

<Field Name="Submitted On">l/2/2006</Field> 

<Field Name="Hours">6</Field> 

<Field Name="Hourly Rate">50</Field> 

</ROW> 

<ROW> 

<Field Name="TimesheetlD">Britta Simon FI-23-123 
l/3/2006</Fieid> 

<Fieid Name="Consuitant">Britta Simon</Fieid> 

<Fieid Name="Project">Fl-23-123</Fieid> 

<Fieid Name="Submitted On">l/3/2006</Fieid> 

<Fieid Name="Hours">5</Fieid> 

<Fieid Name="Houriy Rate">50</Fieid> 

</Row> 

</ROWS> 

</Data> 

</Listlnstance> 

</Eiements> 

Finally, here is the code from a batch file named Install.cmd. This batch file copies files into 
the Windows SharePoint Services Feature directory and runs stsadm.exe commands to install 
the feature and activate it on the site at the URL http://localhost. 

@SET SPDlR="c:\program fiies\common files\microsoft shared\web server extensions\12" 

Echo Deactivating feature 

%SPDlR%\bin\stsadm -o deactivatefeature -filename 

LitwareTimesheets/feature.xml -url http://localhost 
Echo uninstalling feature 

%SPDlR%\bin\stsadm -o uninstall feature -filename LitwareTimesheets/feature.xml 
IISRESET 

Echo Copying files 

rd /s /q %SPDlR%\Template\Features\LitwareTimesheets 

xcopy /e /y Features\LitwareTimesheets\* %SPDlR%\Template\Features\LitwareTimesheets\ 

Echo installing feature 

%SPDlR%\bin\stsadm -o installfeature -filename LitwareTimesheets/feature.xml -force 
IISRESET 

Echo Activating feature 

%SPDlR%\bin\stsadm -o activatefeature -filename LitwareTimesheets/feature.xml 
-url http://localhost -force 

After this batch file is run, users can navigate to the site at the root of the default Web site and 
see that a list has been created named Timesheets. (The Timesheets list will not show up on 
the Quick Launch toolbar, so users would need to click View All Site Content on the Quick 
Launch toolbar to see the list, which is shown in Figure 5-4.) 
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Figure 5-4 The Timesheets list and its data were created and installed through files that define 
a feature. 

Creating a Custom Feature 

Now we’ll walk through the creation of a custom feature. We’ll work with a Visual Studio 
project named LitwareFeatureLab.sln, which contains starter XML files for a feature named 
LitwareFeatureLab and an assembly DLL project that we’ll use to create receiver classes for 
the feature. 

Figure 5-5 shows the feature manifest file, Feature.xml, open in Visual Studio 2005. As you 
can see, this manifest file contains the essential feature attributes, such as the Id, Title, and 
Scope, but nothing else at this point. 

First we’ll add an element manifest to Feature.xml to reference a file named Lightup.xml. 
Lightup.xml contains the feature’s functionality. Here’s the markup included in Lightup.xml 
so you can examine the feature elements defined within it. We’ll simply reference 
Lightup.xml in Feature.xml, which will add the functionality defined in Lightup.xml to the 
feature. 
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Figure 5-5 A bare-bones Feature.xml file 


<?xml version="1.0" encoding="utf-8" ?> 

<Elements xmlns="http://schemas.mlcrosoft.com/sharepoint/"> 

<!-- Create Command Link Site Settings Page —> 

<CustomAction 

ld="SiteSettings" 

Groupld="Customization" 

Location="Microsoft.Sharepoint.SiteSettings" 

Sequence="106" 

Title="Custom Litware Site Setting Command's 

<urlAction url="/_layouts/LitwareFeatureLab.aspx?Command=SiteSettingCommand"/> 
</CustomAction> 

<!-- Add Command to Site Actions Dropdown —> 

<CustomAction ld="SiteActionsToolbar" 

Groupld="SiteActions" 

Location="Microsoft.Sharepoint.StandardMenu" 

Sequence="1000" 

Title="Litware Custom Action" 

Description="Custom Litware Site Action" 
imageurl="/_layouts/images/ACLl6.GIF"> 

<urlAction url="/_layouts/LitwareFeatureLab.aspx?Command=SiteActionCommand"/> 
</CustomAction> 

<!— Document Library Toolbar New Menu Dropdown --> 

<CustomAction ld="DocLibNewToolbar" 

RegistrationType="List" 

Registrationld="101" 

Groupld="NewMenu" 

Rights="ManagePermissions" 

Location="Microsoft.Sharepoint.StandardMenu" 

Sequence="1000" 

Title="Litware Custom New Command" 

Description="This command creates a new Litware doc" 
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imageurl="/_layouts/images/ACLl6.GIF"> 

<urlAction url ="/_layouts/LitwareFeatu reLab.aspx?Command=NewDocCommand"/> 
</CustomAction> 

<!-- Document Library Toolbar Actions Menu Dropdown --> 

<CustomAction ld="DocLibActionsToolbar" 

RegistrationType="List" 

Registrationld="101" 

Groupld="ActionsMenu" 

Location="Microsoft.Sharepoint.StandardMenu" 

Sequence="1000" 

Title="Litware Command on Document Library" 

Description="This command performs a custom command on the document 
1ibrary" 

imageurl="/_layouts/images/ACLl6.GIF"> 

<urlAction url="/_layouts/LitwareFeatureLab.aspx?Command=DocLibCommand"/> 
</CustomAction> 

<!-- Per Item Dropdown (ECB)—> 

<CustomAction 

ld="ECBltemToolbar" 

RegistrationType="List" 

Registrationld="101" 

Type="ECBltem" 

Location="Bugworkaround:LocationShouldEqualEditcontrolBlock" 

Sequence="106" 

Title="Litware ECB Item Command"> 

<urlAction url="/_layouts/LitwareFeatureLab.aspx?Command=SiteSettingCommand"/> 
</CustomAction> 

</Elements> 

In Feature.xml, we add an ElanmtManifest element for Lightup.xml as follows: 

<ElementManifests> 

<ElementManifest Location="Lightup.xml"/> 

</ElementManifests> 

After building the project, we can install the feature using a batch file similar to the Install.cmd 
file shown earlier, but with one small difference. This batch file also copies an application page 
named LitwareFeatureLab.aspx to the _layouts directory. You might notice that this page is 
referenced in the UrlAction attribute in all the CustomAction elements in Lightup.xml. 

After the feature has been installed, we can determine that it is working properly by examining 
the Site Actions menu. We should see the Litware Custom Action command as shown in 
Figure 5-6. 

Go back and examine each of the CustomAction elements in Lightup.xml. Each of these com¬ 
mands shows up in the Windows SharePoint Services user interface. We would need to add a 
document library to the site to test the last three custom actions. 
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Figure 5-6 The Site Actions menu with a custom action added through a feature 

Creating a Callback Receiver Class for a Feature 

Now well write and configure a custom receiver class that fires custom event handlers when¬ 
ever our feature is activated or deactivated within a site. Well use the class library DLL project 
named LitwareFeatureLab as a starting point. This project has been configured to compile the 
output assembly, LitwareFeatureLab.dll, with a strong name and install it into the Global 
Assembly Cache (GAC) any time the project is built. 

We need a reference to Microsoft.SharePoint.dll so that code in the LitwareFeatureLab project 
can use the core Windows SharePoint Services types. The receiver class is contained in the 
source file, LitwareFeatureLabReceiver.es. The following implementation changes the current 
site’s title and description each time the feature is activated or deactivated. 

using System; 

using Microsoft.SharePoint; 
namespace LitwareFeatureLab { 

public class LitwareFeatureLabReceiver : SPFeatureReceiver { 

public override void Featurelnstalled(SPFeatureReceiverProperties 
properties){} 

public override void FeatureuninstallingCSPFeatureReceiverProperties 
properties){} 
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public override void FeatureActivatedfSPFeatureReceiverProperties 
properties) { 

SPWeb web = (SPWeb)properties.Feature.Parent; 
web.Title = "Litware Feature Lab"; 

web.Description = "Litware Feature Lab activated at " + 

DateTime.Now.ToLongTimest ring O; 
web.updateO; 

} 

public override void FeatureDeactivatingCSPFeatureReceiverProperties 
properties) { 

SPWeb web = (SPWeb)properties.Feature.Parent; 
web.Allowunsafeupdates = true; // this is required to prevent 

//errors in beta 1 
web.Title = "Plain Old Team Site"; 

web.Description = "Litware Feature Lab deactivated at " + 

DateTime.Now.ToLongTimest ring(); 
web.updateO ; 

} 

} 

} 

Now we need to modify Feature.xml, using the ReceiverAssembly and ReceiverClass attributes, 
to indicate that there is a source file named LitwareFeatureLabReceiver.es. 

<?xml version="1.0" encoding="utf-8" ?> 

<Feature Id="B0FFE3F6-7F28-45ed-BF94-0B597EE95E53" 

Title="Litware Feature Lab" 

Description="This feature demonstrates Hello world functionality." 
version="l.0.0.0" 

Scope="web" 

ReceiverAssembly="LitwareFeatureLab, version=l.0.0.0, Culture=neutral, 

PublicKeyToken=d4e5777bl6a5749f" 

ReceiverClass="LitwareFeatureLab.LitwareFeatureLabReceiver" 

Hidden="FALSE" 

xmlns="http://schemas.microsoft.com/sharepoint/"> 

<ElementManifests> 

<ElementManifest Location="Lightup.xml"/> 

</ElementManifests> 

</Feature> 

We can now run Install.cmd again to install the feature with the receiver functionality. We can 
test to make sure the functionality is working by going to the Site Features page and deactivat¬ 
ing and reactivating the feature. If the site title and description change, as shown in Figure 5-7, 
we know the receiver callback functionality is working properly. 
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Figure 5-7 A demonstration of receiver functionality in a feature 


Adding a Document Library on Activation 

Let’s say that we want to modify the Litware feature by changing the FeatureActivated event 
handler method so that it creates a document library named Weekly Timesheets. You could 
add the following code to the method as a starting point: 

SPListTemplate template = web.ListTemplates["Document Library"]; 

Guid docLiblD = web.Lists.Add("weekly Timesheets", "Library for Litware weekly 
Timesheets Documents", template); 

SPList docLib = web.Lists[docLiblD] ; 
docLib.OnQuickLaunch = true; 
docLi b. updated ; 


You could also add complementary code to the FeatureDeactivating event handler to remove 
the document library named Weekly Timesheets if it exists: 

try 

{ 

Guid docLiblD = web.Lists["weekly Timesheets"]. id; 
web.Lists.Delete(docLiblD); 

} 

catch (Exception ex) { /* do nothing */ } 
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Adding an Event Handler to the Timesheets List 

Another change we could make to this feature is to add an event handler to the Timesheets 
list. We’d start by creating a new class, named TimesheetEventReceiver , and then implement 
this class as an item event handler by inheriting from SPItanEventReceiver and overriding 
ItanAdding, ItemAdded, ItemUpdating, and ItemUpdated. 

We could implement ItemAdded and ItemUpdated to generate a unique TimesheetID for the 
current item by concatenating a string that contains the values of the Consultant, Project, and 
Submitted On columns. After this unique string is generated, its value is assigned to the cur¬ 
rent item’s TimesheetID column. The code needs to call the Update method on the SPListltem 
object to save the changes. 

We could also implement ItanAdding and ItemUpdating to perform validation of the value 
entered by the user for the Submitted On date. The validation would make sure that the date 
entered is not a day in the future. If the user tries to enter a time sheet item for a future date, 
the action is cancelled and an error message is returned. 

We would also modify the Feature Activated event handler method to register event handlers 
for each of the four events in the TimesheetEventReceiver class. We could use code that looks 
like the following, which refers to ItemUpdated. 

SPList list = web.Lists["Timesheets"]; 
list.EventReceivers.Add( 

SPEventReceiverType.ItemUpdated, 

"LitwareFeatureLabSolution, version=l.0.0.0, Culture=neutral, 

PublicKeyToken=d4e5777b 

"LitwareFeatureLabSolution.TimesheetEventReceiverSolution"); 
list.update(); 

Here’s the code for the TimesheetEventReceiver class, showing the string concatenation and 
validation. 

using System; 

using System.Collections.Generic; 

using System.Text; 

using Microsoft.SharePoint; 

namespace LitwareFeatureLabSolution 
{ 

public class TimesheetEventReceiverSolution : SPltemEventReceiver 
{ 


public override void itemAddingCSPltemEventProperties properties) 
{ 

base.ltemAddingCproperties); 
validateChange(properties); 

} 
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public override void itemupdatingCSPltemEventProperties properties) 

{ 

base.ltemupdatingCproperties); 
validateChange(properties); 

} 

private void validateChange(SPltemEventProperties properties) { 

SPWeb web = properties.OpenwebO ; 

SPListltem timesheet = 

web.Lists[properties.Listld].GetltemByld(properties.Listltemld); 

// check to make sure date is not day in future 

if (Convert.ToDateTime(timesheet["Submitted On"]).CompareTo(DateTime.Today) > 0) 

properties.ErrorMessage = "you cannot enter timesheet for days in future"; 
properties.Cancel = true; 
return; 

} 


} 

public override void ltemAdded(SPltemEventProperties properties) { 
base.ltemAdded(properties); 

GeneratelD(properties); 

} 

public override void ltemupdated(SPltemEventProperties properties) { 
base.ltemupdated(properties); 

GeneratelD(properties); 

} 

private void GeneratelD(SPltemEventProperties properties) { 

SPWeb web = properties .OpenwebO ; 

SPListltem timesheet = 

web.Lists[properties.Listld].GetltemByld(properties.Listltemld); 
// generate TimesheetlD by concatenting Consultant, Project 
// and Submitted On columns 

timesheet["TimesheetlD"] = timesheet["Consultant"] + " " + 
timesheet["Project"] + " " + 

Convert.ToDateTime(timesheet["Submitted 
On"]).ToShortDateString(); ; 
timesheet.updateO; 

} 

} 

} 

And here is the code for the updated receiver class: 

using System; 

using System.Collections.Generic; 

using System.Text; 

using Microsoft.SharePoint; 
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namespace LitwareFeatureLabSolution 

{ 

public class LitwareFeatureLabReceiverSolution : SPFeatureReceiver 

{ 

public override void Featurelnstalled(SPFeatureReceiverProperties 
properties) 

{ 

} 

public override void Featureuninstalling(SPFeatureReceiverproperties 
properties) 

{ 


} 

public override void FeatureActivated(SPFeatureReceiverProperties 
properties) 

{ 

SPWeb web = (SPWeb)properties.Feature.Parent; 
web.Title = "Litware Feature Lab Solution"; 

web.Description = "Litware Feature Lab Solution activated at " + 
DateTime.Now.ToLongTimeStringO; ; 
web.updateO ; 

SPListTemplate template = web.ListTemplates["Document Library"]; 
Guid docLiblD = web.Lists.Add("weekly Timesheets”, "Library for 
Litware weekly Timesheets Documents", template); 

SPList docLib = web.Lists[docLiblD]; 
docLib.OnQuickLaunch = true; 
docLib.updateQ ; 


SPList list = web.Lists["Timesheets"]; 

1ist.OnQuickLaunch = true; 

list.EventReceivers.Add(SPEventReceiverType.itemAdding, 

"LitwareFeatureLabSolution, version=l.0.0.0, Culture=neutral, 
PublicKeyToken=d4e5777bl6a5749f", 

"LitwareFeatureLabSolution.TimesheetEventReceiverSol uti on"); 
list.EventReceivers.Add(SPEventReceiverType.itemAdded, 

"LitwareFeatureLabSolution, version=l.0.0.0, Culture=neutral, 
PublickeyToken=d4e5777bl6a5749f", 

"LitwareFeatureLabSolution.TimesheetEventReceiverSolution"); 


list.EventReceivers.Add(SPEventReceiverType.Itemupdating, 

"LitwareFeatureLabSolution, version=l.0.0.0, Culture=neutral, 
PublickeyToken=d4e5777bl6a5749f", 

"LitwareFeatureLabSolution.TimesheetEventReceiverSolution"); 

list.EventReceivers.Add(SPEventReceiverType.Itemupdated, 

"LitwareFeatureLabSolution, version=l.0.0.0, Culture=neutral, 
PublickeyToken=d4e5777bl6a5749f", 

"Li twareFeatureLabSolution.TimesheetEventReceiverSolution"); 
list.updated ; 


} 
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public override void FeatureDeactivating(SPFeatureReceiverProperties 
properties) 

{ 

SPWeb web = (SPWeb)properties.Feature.Parent; 
web.Allowunsafeupdates = true; 
web.Title = "Plain Old Team Site"; 

web.Description = "Litware Feature Lab Solution deactivated at " + 
DateTime.Now.ToLongTimeStringO ; ; 
web.updateO; 
try 
{ 

Guid docLiblD = web.Lists["weekly Timesheets"].ID; 
web.Lists.Delete(docLiblD); 

} 

catch (Exception ex) { } 
try { 

SPList list = web.Lists["Timesheets"]; 
list.OnQuickLaunch = false; 
list.updateO ; 

} 

catch(Exception ex){] 

} 

} 

} 
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In this chapter, we’ll review some of the primary classes in the Microsoft Windows SharePoint 
Services server-side object model that provide access to objects representing the various 
aspects of a SharePoint site. Well then demonstrate some of these classes and their members 
in action, in examples that take data from a list, serialize the data to XML, add the data to a 
Microsoft Office Word 2007 document, and store the document in a document library. 

Top-Level Classes 

The Microsoft.SharePoint and Microsoft.SharePoint.Administration namespaces provide types 
and members for working with lists and sites and for managing a server or collection of serv¬ 
ers that run Windows SharePoint Services. The following table lists the four major top-level 
classes in these namespaces. Starting with one of these classes, you can work through the 
object model to the class you need to use to work with lists and Web sites or to manage one 
or more servers. 


Class 

Description 

SPGIobalAdmin 

Used for central configuration settings. In particular, you can use this class 
to enumerate the list of virtual servers in Internet Information Services 
(IIS) and access SPVirtualServer objects. 

SPVirtualServer 

Represents a virtual server, and is used for server-wide configuration set¬ 
tings. Use this class to create, delete, and access sites under a specific vir¬ 
tual server. 

SPSite 

Represents a site collection (a top-level site and its subsites), and is used 
for managing existing sites and for accessing site and list data. 

SPWeb 

Represents an individual site, and is used for working with the lists, files, 
and security of the site, including users, site groups, cross-site groups, and 
permissions. 
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Depending on which part of a Windows SharePoint Services deployment you need to custom¬ 
ize and the type of application you are creating, you can use different means of entry into the 
Windows SharePoint Services object model to obtain the higher-level object you need to start 
with. The SPGlobalAdmin class provides access to the highest-level objects in the object hier¬ 
archy. These objects are generally related to administrative operations. You can also use the 
SPGlobalAdmin class to reach objects that are lower in the hierarchy. The SPGlobalAdmin class 
includes a constructor that you can use to obtain an SPGlobalAdmin object to customize glo¬ 
bal administrative settings in a deployment. 

To perform actions on data within a SharePoint site, you must first obtain an SPWeb object, 
which serves as the starting point for accessing lists, items, documents, users, alerts, and so 
on. For example, to return a collection of lists for a site within an HTTP context, you must first 
obtain the SPWeb object by passing the current System.Web.HttpContext object to the GetCon- 
textWeb method of the SPControl class, as shown in this example: 

SPWeb mysite = SPControl.GetContextweb(Context) 

You would then use mySite.Lists to get the collection of lists for the site. Similarly, mySite. Title 
returns the title of the site, and mySite. Users returns the users on the site. 

If you are creating a Web Part, Web service, or Web application to work with site collections, 
individual sites, or lists, use the GetContextSite or GetContextWeb method of the SPControl 
class to obtain the current site collection or site. When you create a Web application in the 
_layouts directory, the application’s functionality becomes available to all sites on the Web 
server. Outside an HTTP context, such as in a console application, use the constructor of the 
SPSite class to obtain a specified site collection. 

Here are descriptions of some of the properties and methods of these and related classes 
that you are likely to use when creating an application for a Windows SharePoint Services 
deployment: 

■ The ContentDatabases property of the SPVirtualServer class returns an SPContent- 
DatabaseCollection object that represents the collection of content databases used for a 
virtual server. Each SPContentDatabase object provides access to properties of the con¬ 
tent database. 

■ The WebServers property of the SPGlobalConfig class returns an SPWebServerCollection 
object representing the collection of front-end Web servers in the Windows SharePoint 
Services deployment. Each SPWebServer object provides access to properties of the Web 
server. 

■ The VirtualServers property of the SPGlobalAdmin class provides access to an SPVirtual- 
ServerCollection object representing all the virtual servers in the Windows SharePoint 
Services deployment. The OpenVirtualServer method of the SPGlobalAdmin class returns 
a specific virtual server. Each SPVirtualServer object has members that can be used to 
manage the virtual server. The Sites property provides access to the SPSiteCollection 
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object representing the collection of site collections on the virtual server, and the Add 
method is used to create top-level site collections. 

■ Each SPSite object represents a site collection and has members that can be used to man¬ 
age the site collection. The AllWebs property provides access to the SPWebCollection 
object that represents the collection of sites within the site collection, including the top- 
level site. The OpenWeb method of the SPSite class returns a specified site. 

■ Each site collection includes any number of SPWeb objects. Each object has members 
that can be used to manage a site (including its template and theme) and also to access 
files and folders on the site. The Webs property returns an SPWebCollection object repre¬ 
senting all the subsites of a specified site, and the Lists property returns an SPListCollec- 
tion object representing all the lists in the site. 

■ Each SPList object has members for managing the list or for accessing items in the list. 
The Getltems method can be used to perform queries that return specific items. The 
Fields property returns an SPFieldCollection object representing the fields (or columns) 
in the list. The Items property returns an SPListltanCollection object representing the 
items (or rows) in the list. 

■ Each SPField object has members that contain settings for the field. 

■ Each SPListltem object represents a single row in the list. 



Note Most classes in the Microsoft.SharePoint and Microsoft.SharePoint.Administration 
namespaces start with SP. Generally, classes in the Windows SharePoint Services assembly that 
don't start with this prefix represent Web form controls. 


Figure 6-1 on the next page shows the relationship between the top-level classes in the Win¬ 
dows SharePoint Services object model and server and site architecture. 

Updating Object Properties 

Windows SharePoint Services does not usually save modifications of object properties to the 
database until you call the Update method on the object. The following example shows how to 
change the title and description for the Tasks list: 

SPList myList = myweb.Lists["Tasks"]; 
myList.Title="New_Titie"; 
myList.Description="List_Description"; 
myList.updateQ ; 



Note An exceptional case is when a document is checked out from a document library. 
Metadata for a document that is checked out from a document library cannot be modified 
using the Update method of the SPListltem object. 
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Figure 6-1 Top-level classes in the Windows SharePoint Services object model 


Working with Collections 

Just as lists are at the center of a SharePoint site, so are collections at the center of its object 
models. You can use each collection to add, delete, enumerate, and update a type of object. 
Collection classes generally share the following traits: 

■ Has a name that ends in “Collection" 

■ Implements the System. Collections.ICollection interface 

■ Has a Count property of type Int32 

■ Has an lnt32 indexer that can be used to get the nth item in the collection 

■ Has an indexer that takes an item identifier 

■ Has Add and Delete methods 

Calling the Add method for a collection usually updates the content database on the server 
with the appropriate data. In cases in which additional information is required to update data, 
however, the Add method returns an object that you use to gather the information. For exam¬ 
ple, to add an item to a list, first use the Add method of the SPListltemCollection class to return 
an SPListltem object, assign values to appropriate properties of that object, and then call the 
Update method to effect changes within the content database. 
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Using Indexers 

Indexers provide a useful means for accessing individual items in collections. To return an 
item, use square brackets ([]) in Microsoft Visual C# (or parentheses in Microsoft Visual Basic 
.NET) to contain either an index or a string that identifies the item within the collection. 

For example, if mySite represents an instance of the SPWeb class, SPList myList = 
my Site. Lists["Announcements"] returns the Announcements list. You can then use the Items 
property for the list object to return all the items in the list ( SPListltemCollection myltems = 
myList. Items). To return only a subset of items from the list, call one of the list object’s Getltems 
methods and pass an SPQuery object to specify the subset. For example, 

SPListltemCollection myltems = myList.Getltems(myQuery) 

You can use an indexer to return a specific field from a list; for example, myList.Items["Field_g 
Name"]. You can also specify a field name in an indexer and iterate through the collection of 
items in a list to return values from the field. The following example, which would require a 
using directive for the Microsoft.SharePoint namespace and a directive for the Microsoft. Share- 
Point.Utilities namespace, displays the Due Date, Status, and Title values for each item in a list: 

foreach(SPListltem myltem in myltems) 

{ 

Response, wri te(SPEncode. Htmi Encode (myltem ["Due Date"] .ToStri ngO) + "<BR>"); 

Response.write(SPEncode.HtmiEncode(myltem["Status"] .ToStringO) + "<BR>") ; 

Response.write(SPEncode.HtmlEncode(myltem[”Title"] .ToStringO) + "<BR>") ; 

} 

The next example shows how to return all Title and Status values for the Tasks list on a Share- 
Point site. (This example would also require a using directive for Microsoft.SharePoint and 
Microsoft. SharePoint.Utilities.) 

SPWeb mySite = SPControl.GetContextweb(Context); 

SPList myTasks = mySite.Lists["Tasks"]; 

SPListltemCol1ection myltems=myTasks.Items; 

foreach(SPListltem myltem in myltems) 

{ 

Response.write(SPEncode.Htm]Encode(myltem["Title"] .ToStringO) + " :: " + 

SPEncode. Htmi Encode(myltem["Status"] .ToStringO) + "<BR>") ; 

} 

You can also use indexers to modify values in a list. In the next example, a list item is added 
to a collection and the values for a URF column are assigned to the item: 

SPListltem myNewltem = myList.Items.Add(); 
myNewltem["URL_Field_Name"] ="url, Field_Description"; 


myNewltem.updateO; 
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Note The URL field type is unique because it involves two values (separated by a comma 
and a space), and in the preceding example these values are both assigned to the new item 
through a single indexer. 


The next example sets the Status and Title values for a list item. 

SPListltem myltem = myltems[0]; 

myltem["Status"]="Not Started"; 
myltem["Titie"]="Task Tit!e"; 


myltem.updateO; 



Note An indexer throws an ArgumentOutOfRange exception if it does not find the specified 
item. 


Determining Where to Build a Custom Application 

The scope of an application affects the location where you build an application that runs 
on Windows SharePoint Services. Custom ASPX pages and Web applications that you 
want to be accessible from all Web sites in a Windows SharePoint Services deployment 
should be stored in the following directory, which supports the _layouts virtual direc¬ 
tory: 

Local_Drive:\Program Files\Common Files\Microsojt Shared\Web Server Extensions\60\ 
TEMPLATE\LAYOUTS 

Pages in this directory are accessible from all Web sites in the Windows SharePoint 
Services deployment through a URL in the following form: 

http://Server_Name/[sites/][Site_Name]/[SubSite_Name]/[...]/_layouts/File_Name.aspx 

You may also want to create Web applications that contain custom code that works 
with the global settings for your deployment. For code that involves only the 
Microsoft.SharePoint.Administration namespace for working with global settings in a 
deployment, Microsoft recommends that the Web application be created on the admin¬ 
istrative port. Build and store ASPX pages and Web applications for the administrative 
port in the following directory: 

Local_Drive:\Program Files\Common Files\Microsojt Shared\Web Server Extensions\60\ 
TEMPLATE\ADMIN\1033 

Pages in this directory are accessible through a URL in the following form: 
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http://localhost:Port_#/File_Name.aspx 


Using the Windows SharePoint Services Object Model 
and the Data in a List 

In the following sections, we’ll continue to add some functionality to a sample SharePoint site. 
Litware, our fictitious business, is a consultancy company that requires each of its consultants 
to fill in a daily time sheet that summarizes the activities the consultant performs during that 
day. The time sheet data is stored in a custom SharePoint list for later use. At the end of each 
week, managers review the time sheets to approve or disapprove the hours submitted. To 
facilitate the review process, we want to generate an Office Word 2007 document that sum¬ 
marizes the work each consultant performs during a week. 

In this example, we’ll perform queries against the Timesheets SharePoint list and aggregate 
the results into a custom XML format. The queries will be executed using the Windows Share- 
Point Services object model, and the results will be aggregated using some custom .NET code. 
Well then use the XML Serializer to write the custom XML data to the console for verification. 
Well start out by viewing the output in a console application, and then well focus on using 
the data in the Timesheets list to update an Office Word 2007 document. Finally, well place 
this document in a SharePoint document library where managers or other users can view it. 

Generating Weekly Time Sheet Aggregate Views 

Well start with a Microsoft Visual Studio 2005 solution named TimesheetAggregator. The 
project contains three files: Program.es, Project.cs, and WeeklyAggregate.es. 

Before we can access any data in SharePoint, we need to establish a connection to the Share- 
Point site. When writing code of your own, don’t forget that the common terminology and the 
SharePoint object model don’t always match up. Remember that site collections are repre¬ 
sented by the SPSite object and sites are represented by the SPWeb object. 

First we add a reference to the Microsoft. Sharepoint assembly. Next we create a Microsoft.Share- 
Point.SPSite object in the Main method to connect to the default SharePoint site. (The URL for 
the example is http://ossl.) We use the SPSite constructor that takes a single string parameter. 
We access the SPWeb object associated with the SharePoint site at http://ossl by using the 
SPSite’s OpenWeb method. By default this method opens the site associated with the URL pro¬ 
vided to the SPSite object’s constructor. 

We then get a reference to the Timesheets list by using the SPWeb object’s Lists property and 
the name of the list, Timesheets. Here is the code from Program.es: 

static void Main(string[] args) 

{ 

// get access to the Sharepoint list 
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SPSite site = new SPSite("http://ossl"); 

SPWeb web = site.OpenwebO; 

SPList list = web.Lists["Timesheets"]; 

Next we create a class to encapsulate the process of aggregating the time sheet values. The 
class, named TimesheetAggregator, contains a single method, GenerateAggregation. This 
method returns an instance of WeeklyAggregation , which is a class that represents the aggrega¬ 
tions you need to generate. The GenerateAggregation method accepts as parameters a string 
representing the consultant whose data you need to aggregate and a DateTime value that rep¬ 
resents a date in the week to aggregate data for. Finally, the method accepts a reference to the 
SPList object containing the data to aggregate. 

namespace TimesheetAggregator 
{ 

class TimesheetAggregator 
{ 

public WeeklyAggregation GenerateAggregationfstring consultant, 

DateTime date, SPList timesheetList) 

{ 

} 

} 

} 

Now that we’ve created the TimesheetAggregator class and the GenerateAggregation method, 
we need to write some code that will perform a query against the list to retrieve data for a 
specific consultant and week. First we calculate the minimum and maximum dates, which 
represent the Sunday and Saturday surrounding the date parameter. Keep in mind that the 
DateTime.DayOjWeek method returns an enumeration with the value 0 for Sunday, 1 for Mon¬ 
day, and so on. You can use the DayOjWeek and AddDays methods to help calculate the min¬ 
imum and maximum dates. 

Next we create an instance of an SPQuery object. The SPQuery object has a constructor that 
allows you to provide a view that will be used to help initialize the query. In this example, we’ll 
use the All Timesheets view. Next we specify the Where section of the query by using the Col¬ 
laboration Application Modeling Language (CAML) shown in the following code. Notice that 
this query requires that the consultant’s name match one in the list and that the submitted 
date be between the minimum and maximum dates. Microsoft.SharePoint.Utilities.SPUtil- 
ity.CreateISO8601DateTimeFromSystemDateTime converts a .NET DateTime object to a string 
that is acceptable to the CAML parser. 

Finally, the code calls the SPList. Getltems method using the query we’ve built. This call returns 
a collection of SPListltem objects that represent time sheet entries for the specified consultant 
and week. 

public WeeklyAggregation GenerateAggregation(string consultant, DateTime date, 

SPList timesheetList) 

{ 
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// calculate the min and max dates for the week 
DateTime minDate = date.AddDays(-(int)date.DayOfweek); 

DateTime maxDate = mlnDate.AddDays(6); 

// retrieve the list items for the consultant and week 

SPQuery query = new SPQuery(timesheetList.views["All Timesheets"]); 

query.Query = 

"<where>" + 

"<And>" + 

"<EqxFieldRef Name='Consultant'/xvalue Type='Text'>" + 
consultant + 

"</valuex/Eq>" + 

"<And>" + 

"<GeqxFi el dRef Name= 1 Submi tted_x0020_On 1 /xval ue 
Type='DateTime'>" + 

SPUtility.CreatelS0860lDateTimeFromSystemDateTime(minDate) + 
"</valuex/Geq>" + 

"<LeqxFi el dRef Name=' Submi tted_x0020_On 1 /xval ue 
Type='DateTime'>" + 

SPUti1ity.CreatelS0860lDateTimeFromSystemDateTime(maxDate) + 
"</valuex/Leq>" + 

"</And>" + 

"</And>" + 

"</where>"; 

SPListltemCollection results = timesheetList.Getltems(query); 

Now that we have the SPListltem objects that apply to the consultant and week in question, 
we need to group the hours by project. To do this, we write code in classes named Weekly- 
Aggregation and Project that loops through each SPListltem in the collection returned from the 
query. These classes are designed to serialize into the appropriate XML when submitted to the 
System.Xml.Serialization.XmlSerializer class. 

We create an instance of System.Collections.Generic.Dictionary by using a string as the key and 
Project as the value. This dictionary will be used to store the grouped project hours. Next we 
loop through each SPListltem in the results from the query and retrieve the values from the list 
item by using the indexer and by providing the name of the field. Notice in the code that 
spaces are encoded as _x0020_. 

If the project hasn’t already been added to the dictionary, we create a new instance of a Project 
object, initialize its Name and HourlyRate properties based on the list item, and then add it to 
the dictionary. Finally, for each list item, we retrieve the appropriate Project object from the 
dictionary and increment the hours based on the current list item. 

// create the project aggregates 

Dictionary<string, Project> projects = new Dicfionary<string, Project>(); 
foreach (SPListltem listltem in results) 

{ 

// retrieve the values from the list item 
string project = 1istltem["Project"].ToString(); 
int hours = Convert.Tolnt32(listltem["Hours"]); 

decimal hourlyRate = Convert.ToDecimal(listltem["Hourly_x0020_Rate"]); 
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// check if we already have data for the project 
if (!projects.Containskey(project)) 

{ 

// create a new project record 
project newProject = new ProjectO; 
newProject.Name = project; 
newProject.HourlyRate = hourlyRate; 
newProject.Hours = 0; 

// store the project in the dictionary 
projects.Add(project, newProject); 

} 

// add the current item's hours to the total 
projects[project].Hours += hours; 

} 

At this point, we’ve retrieved the data and grouped the hours by project. Next we need to 
build the aggregated totals and Project objects into the Weekly Aggregation object. The primary 
focus of this step is to take the groupings from the previous step, copy them into the Weekly- 
Aggregation object, and perform some calculations on the data to come up with the totals. 

First we create an instance of the Weekly Aggregation object and initialize the Consultant and 
WeekStarting properties based on the consultant parameter and the minDate value calculated 
earlier. Next we initialize the total hours and total pay to 0 so that these values have a starting 
point for the totals to be calculated. Because the previous grouping already created the Project 
objects that are contained within the Weekly Aggregation object, all we have to do is create a 
new array and copy the data from the dictionary into the array. 

Finally, we need to loop through each item in the projects array and perform two tasks: calcu¬ 
late the project’s total pay by multiplying the hours by the hourly rate, and increment the 
totals in the Weedy Aggregation object. Having initialized the Weekly Aggregation value, we 
return it from the GenerateAggregation method. 

// irvitia]ize the weekly aggregates object 
weeklyAggregation aggregation = new weeklyAggregationO; 
aggregation.Consultant = consultant; 
aggregation.weekstarting = minDate; 
aggregation.TotalHours = 0; 
aggregation.TotalPay = 0.0M; 

// copy the project objects from the dictionary and calculate the totals 
aggregation.Project = new Project[projects.Count]; 
projects.values.CopyTo(aggregation.Project, 0); 
foreach (Project project in aggregation.Project) 

{ 

project.TotalPay = project.Hours * project.HourlyRate; 
aggregation.TotalHours += project.Hours; 
aggregation.TotalPay += project.TotalPay; 

} 


// return the results 
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return aggregation; 

} 

We can test the GenerateAggregation method by calling it with some hard-coded parameters. 
For example, we can call GenerateAggregation from the Main method in the Program.es file 
using Britta Simon as the consultant and January 2, 2006 as the date. To see the results, we 
have two options. One is to look at the data in the WeeklyAggregation object in the debugger; 
the other is to serialize the WeeklyAggregation object to the console. Here is the serialization 
code. 

// perform the aggregations 

TimesheetAggregator aggregator = new TimesheetAggregatorO; 

WeeklyAggregation aggregation = aggregator.GenerateAggregation("Britta Simon", 
new DateTime(2006, 1, 7), list); 

// write the aggregation to the console 

xmlserializer serializer = new xmlSerializer(typeof(weeklyAggregation)); 
serializer.Serialize(Console.Out, aggregation); 

We can test the code by running the console application. Figure 6-2 shows the console dis¬ 
playing an XML document that contains the aggregation of all hours submitted by Britta 
Simon for the week of January 2, 2006. 




Figure 6-2 Data from a SharePoint list serialized to XML 

Using the Packaging API to Stuff Weekly Time Sheet Aggregates into 
Word Documents 

In this example, we’ll use the WeeklyAggregation object created in the previous example, seri¬ 
alize it to XML, and store it in an Office Word 2007 document that is designed to display the 
total hours for a consultant grouped by project. This summary document will be written to 
the file system for now, but in the next example it will be stored in a SharePoint document 
library, where a manager could approve or disapprove the hours submitted. 




<?xml uersion="l.0” encoding="IBM437”?> 

<WeeklyAggregation xmlns :xsi="http:/Vwww. w3 .org/2001/XMLSchema-instance" xmlns :x 
sd="http://'www. w3 .org/2001/XMLSchema" consultant="Britta Simon'’ weekStarting="20 
06-01-01T00:00:00” totalHours=”35” totalPay="1780.0"> 

<Project name="FI-23-123’’ hours="32" hourlyRate="50'’ totalPay="1600" /> 
<Project name ='’MR-23-123" houi*s="3'’ hourlyRate="60” totalPay="180” /> 
</Ueeklyftggregation > 
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The first step in generating the time sheet summary document is to store a template document 
somewhere. In this case, we’ll store the document template (a file named Template.docx) in a 
resource that will be compiled into the assembly. 

In the project properties window, we select the Resources tab, and then click the link to create 
a new resource file for the project. We add the Template.docx file as a resource by clicking the 
drop-down arrow on the Add Resource button and selecting Add Existing File. The name of 
the resource is Template. 

We next add a GenerateDocument method to the TimesheetAggregator class. This method 
should return an array of bytes and accept a WeeklyAggregation object as a parameter. 

public byte[] GenerateDocument(weeklyAggregation aggregation) 

{ 

} 

Now we need to read the Template.docx resource into a memory stream for use by the pro¬ 
gram later. To start this process, we create an instance of System.IO.Memory Stream to work in. 
This stream will be used initially to store the template and later the updated document. Next 
we write the byte array from the resources into the stream using the Stream.Write method of 
the Stream class. To access the byte array, we use the Properties.Resources.Template property 
that is generated automatically by Visual Studio 2005 based on the resource we added earlier. 
Finally, we need to be sure to reset the stream’s location to 0 by using the Stream.Seek method 
so that future reads will start from the beginning. 

// create a memory stream to process the file in 
using (MemoryStream stream = new MemoryStreamO) 

{ 

// read the template from the library and load it into the stream 
byte[] template = Properties.Resources.Template; 
stream.writeftemplate, 0, tempi ate.Length); 
stream.Seek(0, SeekOrigin.Begin); 

Having read the template into the stream, we need to open it by using the packaging APIs in 
System.IO.Packaging and then modify the timesheetData.xml part. We need to add a reference 
to the WindowsBase assembly that is part of WinFX. This assembly is located in the C:\WIN- 
DOWS\msagent\Windows\v6.0.5070 folder. 

We next create an instance of a System.IO.Packaging.Package object by using the static method 
ZipPackage.Open and the stream from the previous step. The file needs to be opened with read 
and write access. Next we create a new relative Uri object with a path of /customXMF/ 
timesheetData.xml. Finally, the code opens the file part using the Package.GetPart method and 
stores the PackagePart object for later. 
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// open the word document and find the timesheet chunk 

package file = zippackage.Open(stream, FiieMode.Open, FileAccess.Readwrite); 
uri xmiparturi = new uri("/customXML/timesheetData.xml", urikind.Relative); 
packagepart xmlpart = file.GetPart(xmlParturi); 

The last step in modifying the template document is to write data to the XML PackagePart by 
using the XmlSerializer class. To do this we need to get access to the part and then write the 
new data to the part’s stream. We first create an instance of the System.Xml.Serialization.Xml- 
Serializer class for the WeeklyAggregation class. Next we retrieve a stream object from the XML 
part by using the PackagePart.GetStream method, making sure that the object is opened for 
reading and writing. We then serialize the aggregation data to the stream retrieved from the 
PackagePart.GetStream call. The length of the stream should be set to 0 before writing. If it 
isn’t, extra data may be left at the end of the stream if the new document is smaller than the 
old one. 

// serialize the weekly aggregation to the part 

XmlSerializer serializer = new xmlSerializer(typeof(weeklyAggregation)); 
using (Stream xmlData = xmlpart.GetStream(FileMode.Open, 

FileAccess.Readwrite)) 

{ 

xml Data.SetLength(0); // this makes sure there's nothing left in the 
// stream 

serializer.Serialize(xmlData, aggregation); 

} 

Now that the updates to the package part are finished, we flush the changes to the stream and 
close the package by using the Flush and Close methods of the Package object. 


// close the file 
fil e. FlushO ; 
file.Close(); 

The final step of implementing the GenerateDocument method is to return the byte array 
stored within the M emoryStream object. We use the M emoryStream.ToArray method to return 
the internal byte array from the GenerateDocument method. 

// return the byte array containing the data in the stream 
return stream.ToArrayO; 

Now that we’ve completed the GenerateDocument method, we can write some code in the 
Main method to test it. We call GenerateDocument using the output of GenerateAggregation and 
then write the resulting byte array to a file. 

byte[] document = aggregator.GenerateDocument(aggregation); 

// write the file to the file system 

using (System.10.Filestream writer = System.10.File.Create(@”C:\Exercise 2 
Test.docx")) 

writer.write(document, 0, document.Length); 
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Figure 6-3 on the next page shows that this version of the application produces the same 
results as the console application with one exception: the data is stored in a Word file contain¬ 
ing a formatted version of the weekly aggregations that is saved on the hard disk. 



Figure 6-3 The list data is now captured in a formatted Word file. 


Adding Word Documents to a Document Library 

In this section, we’ll take the Word document created in the previous example and store it in 
the Weekly Timesheets document library so that managers and users have access to it 
through our SharePoint site. 

We need to add code to the Main method to access the SPDocumentLibrary object for the doc¬ 
ument library. Gaining access to the library is similar to gaining access to the Timesheets list, 
in that you need to use the Lists property of the SPWeb object. The difference is that the SPList 
object is then cast to a specialized list type of SPDocumentLibrary. 

SPDocumentLibrary library = web.Lists["weekly Timesheets"] as 
SPDocumentLibrary; 

Next we create the StoreDocument method for the TimesheetAggregator object to encapsulate 
the creation of the new document in the document library. This method should take three 
parameters: a byte array named document, a string called documentName, and a reference to an 
SPDocumentLibrary object named library. 
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public void StoreDocument(byte[] document, string documentName, 

SPDocumentLibrary library) 

{ 

} 

To add a document to the library, we’ll perform three steps in implementing the StoreDocu¬ 
ment method. First we determine the URL of the document library. To do this, we access the 
ParentWeb property of the SPDocumentLibrary object to get access to the SPWeb object. Then 
we get the SPSite object using the SPWeb.Site property. Finally, we call the SPSite.MakeFullUrl 
method to get the full URL based on the library’s server-relative URL that is found using 
SPDocumentLibrary. RootFolder.ServerRelativeUrl. 

In the next step, we use the URL of the document library and the documentName parameter to 
generate the document path. The third step is to add the file by using the SPWeb.Files collec¬ 
tion and calling the Add method. The parameters needed by this method are the path to the 
new document, the array of bytes representing the file, and a Boolean flag specifying whether 
the file should be overwritten if it already exists. 

// generate the document path 

string librarypath = library.ParentWeb.Site.MakeFullurl 
(1ibrary.RootFolder.ServerRelativeurl); 
string documentpath = librarypath + "/" + documentName; 

// add the document to the library 

1ibrary.ParentWeb.Files.Add(documentPath, document, true); 

To use the completed StoreDocument method, we can call it from the Main method. First we 
generate a unique file name based on the Consultant and WeekStarting parameters from the 
WeeklyAggregation objects. Next we call StoreDocument using the document byte array from 
the GenerateDocument method, the document name, and the document library named Weekly 
Timesheets. 

string documentName = string.Format("{0} {l:MM-dd-yyyy}.docx", 
aggregation.Consultant, aggregation.weekstarting); 
aggregator.StoreDocument(document, documentName, library); 

We can now run the application and verify that the output is in the Weekly Timesheets docu¬ 
ment library. 

Using an Event Handler to Generate Weekly Aggregate Documents 

Having written the components to aggregate time sheets, we can now automate the process. 
Every time an item in a list is changed, Windows SharePoint Services fires an event that you 
can capture and use to perform processing. In this section, we’ll take the code written in the 
previous examples and use it to update the weekly aggregate time sheets each time a related 
time sheet entry is made or updated. 
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The first step is to create a new class, named TimesheetEventHandler, to contain the implemen¬ 
tation of the SharePoint list event handler. The only change needed to the event handler class 
is to make it derive from SPItemEventReceiver. 

using System; 

using System.Collections.Generic; 
using System.Text; 
using Microsoft.SharePoint; 
namespace TimesheetAggregator 
{ 

public class TimesheetEventHandler : SPItemEventReceiver 
{ 

} 

} 

Next we need to override the ItemAdded and ItemUpdated methods and use their parameters 
to get access to the SPListltem object that has changed. In both methods, we need to get access 
to the SPWeb object containing SPListltem. To do this, we use the SPItemEventProperties object 
and call its OpenWeb method. Finally, we gain access to the SPListltem object by using the 
SPWeb.Lists property, and then use SPList.GetltemByld to get the SPListltem object that has 
changed. The Listld and the Listltemld properties in the SPItemEventProperties object contain 
the IDs for the list and list item that have changed. 

public override void ltemAdded(SPltemEventProperties properties) 

{ 

base.ItemAdded(properties); 

// get access to the list item that has been changed 
SPWeb web = properties.OpenwebO ; 

SPListltem listltem = web.Lists[properties.Listld]. 

GetltemByld(properties.Listltemld); 

} 

public override void ltemupdated(SPltemEventProperties properties) 

{ 

base.ItemUpdated(properties); 

// get access to the list item that has been changed 
SPWeb web = properti es .OpenwebO ; 

SPListltem listltem = web.Lists[properties.Listld].GetltemByld 
(properties.Listltemld); 

} 

With references to the SPWeb and SPListltem objects of the item that has changed, we can per¬ 
form the operations from the previous examples on SPListltem. To perform these operations 
and share them between both event handler methods, we can put this code into a single 
method, named UpdateWeeklyTimesheet, and have it accept two parameters, the SPWeb object 
and the SPListltem object. 

We start by retrieving the SPList object by using the SPListltem.ParentList property and the 
SPDocumentLibrary object by using the SPWeb.Lists property, and typecasting SPList to an 
SPDocumentLibrary object. Next we retrieve the consultant’s name and the submitted-on date 
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from the list item. Finally, we process the data in the Main method, as we did in the previous 
examples but with one difference. Instead of providing hard-coded consultant and date 
parameters, we use the values retrieved from the SPListltem object. (We also need to call 
UpdateWeeklyTimesheet from both ItemAdded and ItemUpdated .) 


private void updateweekiyTimesheet(SPWeb web, SPListltem iistltem) 

{ 


// get the list and document library 
SPList list = Iistltem.ParentList; 

SPDocumentLibrary library = web.Lists["weekly Timesheets"] as 
SPDocumentLibrary; 

// get the list item information 

string consultant = listltem["Consultant"] .ToStringO ; 

DateTime submittedon = Convert.ToDateTime(listltem["Submitted_x0020_On"]); 

// process the data 

TimesheetAggregator aggregator = new TimesheetAggregatorO; 
weeklyAggregation aggregation = aggregator.GenerateAggregationCconsultant, 
submittedon, list); 

byte[] document = aggregator.GenerateDocument(aggregation); 
string documentName = string.Format("{0} {l:MM-dd-yyyy}.docx", 
aggregation.Consultant, aggregation.weekstarting); 
aggregator.StoreDocument(document, documentName, library); 

} 

Adding the Assembly to the GAC 

Because we turned this project into a SharePoint event handler, we need to convert it to a class 
library and put the assembly into the Global Assembly Cache (GAC). To do this, we open the 
project properties window in Visual Studio, select the Application tab, and change Output 
Type to Class Library. Next we sign the assembly using TimesheetAggregator.snk. To sign the 
assembly, we click the Signing tab in the properties window, select the Sign The Assembly 
option, and select TimesheetAggregator.snk. Also, on the Build Events tab of the properties 
window, we need to add the following command to the post-build event command line sec¬ 
tion. This line will add the assembly to the GAC after it is built. 

"%programfiles%\Microsoft visual Studio 8\SDK\v2.0\Bin\gacutil.exe" 

-if $(TargetDir)\TimesheetAggregator.dll 

Registering the Event Handler Assembly 

We also need to register the event handler, and one way to do this is to use the SharePoint 
object model to write a simple application that will install the handler. We’ll do this using 
a console application project, named TimesheetAggregatorlnstaller, that we can add to the 
solution. 

We need to add entries to the SPList.EventReceiver collection, which is where an assembly and 
class are associated with an event fired by the list. The first step is to open the SPList object in 
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the same manner as we did in the previous examples—open the site (http://ossl) and get a 
reference to the Timesheets list. 

We next add entries to the SPList.EventReceivers list. One entry is for the ItemAdded event and 
the other for ItemUpdated. For the assembly and class names, we use the values shown in the 
code example that follows. We can then build the application and run it to install the event 
handlers. 

// get access to the SharePoint list 
SPSite site = new SPSite("http://ossl"); 

SPWeb web = site.0penweb(); 

SPList list = web.Lists["Timesheets"]; 

// add the event handler 

list.EventReceivers.Add(SPEventReceiverType.ItemAdded, 

"TimesheetAggregator, version=l.0.0.0, Culture=neutral, 

PublicKeyToken=6479e6da8b088665", 

"TimesheetAggregator.TimesheetEventHandler"); 
list.EventReceivers.AddfSPEventReceiverType.Itemupdated, 

"TimesheetAggregator, version=l.0.0.0, Culture=neutral , 

PublicKeyToken=6479e6da8b088665", 

"TimesheetAggregator.TimesheetEventHandler"); 
list.update(); 

In the examples demonstrated in this chapter, the code was run under the Administrator 
account, so all of the object model operations were performed using an account that had full 
control of the http://ossl site, ldowever, the event handler runs under the account of the 
application pool, Network Service, which means we need to give the Network Service account 
Contributor permissions to the http://ossl site. To grant permission to this account, follow 
these steps: 

1. Open http://ossl (or your top-level site), open the Site Settings page, and then click the 
Advanced Permissions link. 

2. Click Add Users, enter Network Service, and give that account Contributor permissions. 

Finally, it’s time to test the application by navigating to the Timesheets list and creating a new 
;ntry. We’ve used the consultant John Rodman, project FI 23 123, and the date 1/2/2006. — 
vVe can verify that the event handler is working by navigating to the Weekly Timesheets doc- 
ament library and checking whether the new summary document was created, and Figure 6- 
1 shows that it was. 



Note There is another way to install an event handler. The information about which event to 
handle and what assembly will handle it can also be installed in a feature. For more information 
about features, see Chapter 5, "Working with Features in Windows SharePoint Services." 
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Figure 6-4 The time sheet summary document automatically generated in a document library 
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In this chapter: 
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Not so long ago, the final output of a business productivity application was a paper document. 
As an element or outcome of a business process, that document was then mailed, faxed, or 
placed in an in box for activities such as review, approval, or archiving. 

Information workers who created and worked with these documents were part of often 
loosely defined business processes. Those processes have remained elusive, and until now 
they have been difficult to define with any degree of precision or reproducibility. Even when 
e-mail became the distribution mechanism of choice, once an individual finished his or her 
tasks with a document, there was still the question “What happens next?” 

With the 2007 Microsoft Office system, information workers and developers who build appli¬ 
cations for them can answer that question by associating a workflow and workflow activities 
to a document library, list, or content type that is part of a Microsoft Windows SharePoint Ser¬ 
vices site. Workflows provide a solution to automating business processes related to docu¬ 
ment creation and management. In the future, many documents authored in Microsoft Office 
applications will be part of some kind of formal workflow process. 

Workflows and Activities 

The workflow functionality in Windows SharePoint Services is based on the Windows Work- 
flow Foundation (WF), a set of base workflow technologies that programmers can access 
through WinFX. WF also provides tools for the development and execution of workflow- 
based applications. 
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There are two ways to think of workflows. Both types are supported by WF, and you can cre¬ 
ate either type for Windows SharePoint Services. 

■ Sequential workflows are modeled as flowcharts and are well suited for system-oriented 
workflows. A sequential workflow represents a sequence of steps that occur in order 
until the last step is completed. However, sequential workflows can be affected by exter¬ 
nal events and include parallel logical paths, so the precise order in which activities are 
executed can vary. 

■ State machine workflows are modeled as state diagrams and are best suited for human- 
based workflows. A state machine workflow represents a set of states, transitions, and 
actions. One state is denoted the start state, and based on an event, a transition is made 
to another state. The state machine can have a final state that determines the end of the 
workflow. State machine workflows are effective at capturing processes that can be 
changed as they run. For example, a bank manager might override and approve a loan 
application for a customer with a bad credit history on the basis of specific circum¬ 
stances that are not modeled in the original workflow. 

The two main concepts in WF are the workflow and the activity. A workflow represents a coor¬ 
dinated, event-driven set of activities and is compiled into a .NET assembly. An activity is a 
.NET class written in managed code that exposes methods and properties and fires events. A 
workflow runs by conditionally executing the methods in the activities. 

A workflow lets you associate a business process to items on a SharePoint site. For example, 
you can create a simple workflow that routes a document to a series of users for approval or 
develop more complex workflows that involve multiple steps, including conditional branch¬ 
ing, throughout the life cycle of an item. Workflows can be initiated by a user or designed so 
that Windows SharePoint Services initiates the workflow when an event occurs; for example, 
when an item in a list or document library is created or modified. 

A workflow can also be added to a content type, and multiple workflows can be associated 
with a specific item. More than one workflow can run on the same item at the same time, but 
only one instance of a workflow can run on an item at any given time. For example, you might 
have workflows named Loan Approval and Document Preparation associated with a content 
type named Loan Application. Although both workflows can run simultaneously on an item 
of the Loan Application content type, you can’t have two instances of the Loan Approval 
workflow running on the same item at the same time. 

Windows SharePoint Services provides a set of basic workflows and support services that are 
built on WF. In turn, Microsoft Office SharePoint Server 2007 can make use of Windows 
SharePoint Services to implement more sophisticated workflows. Examples of workflows 
include moderation, approval, issue tracking, collecting feedback, and collecting signatures. 
Some of the built-in activities include task management activities such as creating a task, com¬ 
pleting a task, or deleting a task; and item activities such as updating an item or changing an 
item’s status. 
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Note The workflows and activities just mentioned are accurate at the time of writing but 
might change by the time the 2007 Microsoft Office system is released. 


WF is tightly integrated with Microsoft Exchange and Microsoft Office Outlook. For example, 
workflows can generate tasks for individuals that will appear in the Outlook task list. Work- 
flows can also send e-mail messages and time out if the message has not been acted on within 
a set time. The action can then be escalated to another user. The 2007 Microsoft Office system 
client applications are fully workflow aware. For example, Microsoft Office Word 2007, 
Microsoft Office Excel 2007, and Microsoft Office PowerPoint 2007 are enabled for workflow 
initiation, configuration, and completion. Microsoft Office Access 2007 can also take advan¬ 
tage of workflows for reporting. 

Windows Workflow Foundation Run-Time Engine 

The WF run-time engine manages workflow execution and enables workflows to remain 
active for long periods of time and survive machine reboots. The WF run-time engine provides 
services to workflow applications, including sequencing, state management, tracking capabil¬ 
ities, and transaction support. The engine serves as a state machine responsible for loading 
and unloading workflow templates in addition to managing the current state of any work- 
flows that are running. 

WF allows any application process or service container to run workflows by loading WF 
within its process. For Windows SharePoint Services workflows, SharePoint hosts WF. In 
place of the pluggable services that are included with WF, Windows SharePoint Services pro¬ 
vides its own implementations of services for transactions, persistence, notifications, roles, 
tracking, and messaging. The functionality of the WF run-time engine, in addition to the host¬ 
ing functionality that Windows SharePoint Services provides, is exposed through the Win¬ 
dows SharePoint Services object model. 

Building Custom Workflows 

The basic workflow activities provided by Windows SharePoint Services offer the means to 
define sophisticated workflows. Sometimes, however, you’ll need to build your own activities. 
For example, within a health care application, a developer might want to send a Flealth Level 
Seven (HL7) message to request an X ray or a drug for a patient after it has been approved by 
a doctor. 

Activities can be readily built with managed code in Microsoft Visual Studio 2007. Workflows 
can be created with Microsoft Office SharePoint Designer 2007 and with the Microsoft Visual 
Studio 2005 Designer for Windows Workflow Foundation. Workflows can also be custom¬ 
ized through the user interface in Windows SharePoint Services itself. 
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To manage complex workflows, you’ll need to create a form or a series of forms for associating 
and configuring the workflow, initializing the workflow, and for gathering user input required 
for a workflow. If you build a workflow using Office SharePoint Designer, the forms are gen¬ 
erated for you as .aspx pages. If you use Visual Studio, you can also use Microsoft Office 
InfoPath 2007 forms. Office InfoPath 2007 forms will run inside the browser or natively on 
the client if Office InfoPath 2007 is installed. 


More Info For more information about running Office InfoPath 2007 forms in the browser, 
see Chapter 9, “Microsoft Office InfoPath 2007 and Microsoft Office Forms Server 2007." 


The Visual Studio 2005 Designer for Windows Workflow Foundation is an add-in hosted 
within Visual Studio 2005. Developers can use this tool to create custom workflows and 
workflow activities. A workflow can be created using graphical elements, XML specification, 
code, or a combination of these. The designer provides a graphical design surface that devel¬ 
opers can use to easily assemble and configure predefined activities into a custom workflow. 
Workflow authors use and extend the workflow model in the same way they use and extend 
other elements of the Microsoft .NET Framework. 

The Visual Studio 2005 Designer for Windows Workflow Foundation includes a number of 
predefined activities you can use to create Windows SharePoint Services workflows. In addi¬ 
tion, Windows SharePoint Services provides a number of activities specifically for use in Win¬ 
dows SharePoint Services workflows. These activities are optimized to simplify and streamline 
development of workflows for use on SharePoint sites. 

Because not all the activities available in the Visual Studio 2005 Designer for Windows Work- 
flow Foundation are relevant in the context of SharePoint sites, Windows SharePoint Services 
supports a subset of the available activities. These include the following: 

■ Code Use this activity to add Visual Basic or C# code to your workflow. 

■ ConditionedActivityGroup Use this activity to perform a set of activities condition¬ 
ally, based on criteria specific to each activity, until a condition is met for the 
ConditionedActivityGroup activity as a whole. 

■ Scope Use this activity to logically group activities to provide a framework for 
transaction and exception handling. 

■ Sequence Use this activity to execute an ordered set of child activities. 

■ Replicator Use this activity to create multiple instances of a single child activity. 

Windows SharePoint Services provides specific activities that help in three main areas: creat¬ 
ing, updating, completing, and deleting SharePoint tasks; creating, updating, and deleting 
SharePoint task alerts; and enabling workflow forms within specific scopes to allow users to 
modify workflows that are in progress. 
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Installation and Deployment 

To install a workflow on a server farm, you need to create a workflow definition, which is an 
XML file that contains the information Windows SharePoint Services requires to instantiate 
and run the workflow. This information includes the name, GUID, and description of the 
workflow; the location of any custom forms used in this workflow; and the correct class 
within the workflow assembly to call. 

Each server farm contains a workflow associations table, and each entry in this table contains 
data about a workflow’s association with a specific content type, list, or document library. This 
data usually indicates whether the workflow is started automatically or by users and provides 
the task and history lists associated with the workflow. If a workflow has been added to mul¬ 
tiple content types, lists, or document libraries, it will have one entry in the table for each asso¬ 
ciation. Likewise, if a specific content type, list, or document library is associated with 
multiple workflows, the table includes an entry for each of these workflows. 

Workflow Stages 

Users, including administrators and end users, interact with workflows at various stages. 
Among these stages are association, initiation, status, and completion. The following sections 
describe some of these stages in more detail. 

Workflow Association 

Workflows are installed at the server level. The administrator of a site collection must activate 
the workflow to make it available to a specific site collection on that server. Site administrators 
can then associate a specific workflow with a list, document library, or content type. A work- 
flow association is stored as a property of the specific list or other item. Administrators can 
also set general workflow parameter information such as 

■ A unique name for the workflow 

■ How the workflow is applied to a given item (either automatically when the item is cre¬ 
ated or changed or manually) and which roles (such as Administrator or Contributor) 
can start a workflow 

■ The task list for the workflow to use if it creates tasks 

■ The history list for the workflow to store history events, as defined by the workflow 

In addition, a site administrator can specify custom parameter information for a particular 
workflow. To capture this information, the workflow must provide its own form that Win¬ 
dows SharePoint Services displays for the administrator. 
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Workflow Initiation 

Any user who has been assigned the appropriate role can initiate a workflow that is config¬ 
ured to run manually. The user selects the item on a SharePoint site and then selects the work- 
flow from the group of workflows associated with that item. The user supplies any 
information required for the specific workflow and then starts the workflow. Initiating a work- 
flow creates a new workflow instance for that specific item. 

Again, for a user to specify custom workflow initiation settings, the workflow must provide its 
own form. The user specifies the initiation settings on this form, and the settings are passed to 
the workflow engine, which starts the workflow instance. 

Workflow Status 

Users can view the progress of a workflow on a selected item. The main document library or 
list item page displays the status of the workflows running on an item. In addition, each item 
has a workflow page on which a user can see all workflows currently running on that item, all 
workflows that have run on the item in the past, and all the workflows available for that item. 

When a user initiates a workflow on an item, Windows SharePoint Services adds a column to 
that item, and the column’s name is initially set to the name of the workflow. Windows Share- 
Point Services uses this column to display the current status of the item within that workflow. 

Workflow Task Completion 

Workflow stages appear as tasks in a task list. When designing a workflow, its author can 
specify the task schema, which might include information such as the following: 

■ Task title 

■ Name of the person the task is assigned to 

■ Task status 

■ Task priority 

■ Task date due 

■ A link to the referenced item 

As the workflow runs and tasks are created, the user can select the task, mark it complete, and 
enter any optional or required information. The workflow instance is then notified of changes 
to workflow tasks and can choose to respond to those changes as specified in the workflow. 
This response can include moving the item to another stage of the workflow. 
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The OnWorkflowActivated Activity 

All Windows SharePoint Services workflows start with the OnWorkflowActivated activity. 
(Each new SharePoint workflow application project you create contains an OnWorkflow¬ 
Activated activity as the first activity by default. However, you still must set the properties of 
that activity.) This activity initializes the correlation between the workflow instance and the 
correlation reference so that the WF runtime can direct incoming messages to the workflow 
instance. 

Using the Information in the OnWorkflowActivated Activity 

After a Windows SharePoint Services workflow is initiated, the Properties property of the 
OnWorkflowActivated activity returns an SPWorkjlowActivationProperties object that repre¬ 
sents the initial properties of the workflow as it starts, such as the user who added the work- 
flow and the list and item to which the workflow was added. Any activity that needs access 
to the initialization information of the workflow, such as the workflow ID, can refer to the 
Properties object defined in the OnWorkflowActivated activity. 

You can use the initiation properties from any other activity within the workflow; these are 
especially useful when you are using a Code activity to work with the Windows SharePoint 
Services item the workflow is running on. For example, you can use the following code to 
return the SPListltem object on which the workflow instance is running. In the code sample, 
wfProperties is the object variable specified for the Properties property of the OnWorkflow¬ 
Activated activity. 

SPWeb myweb = new SPSite(wfproperties.Siteld) .Openweb(wfproperties.webld); 

SPListltem myltem = 

myweb.Lists[wfproperties.Listld].GetltemByld(wfProperties.Itemld); 

//Here is where you can alter the item... 
myltem.updateO ; 

Setting the Properties of the OnWorkflowActivated Activity 

When you create a SharePoint workflow application project, an OnWorkflowActivated activ¬ 
ity is the first activity by default. Several of the activity’s properties need to be specified. Each 
required property that has not been specified is highlighted with an exclamation-point icon 
in the properties window. To ensure that the OnWorkflowActivated activity is valid, do the 
following: 

■ Set the Activation property to True. You must set this property to True for the workflow 
to initialize properly. 

■ Specify variables for the following properties: 

□ Properties 

□ CorrelationRejerence 

□ Workflowld 
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How Windows SharePoint Services Processes Workflows 

Windows SharePoint Services runs a workflow until the workflow reaches a point at 
which it cannot proceed until a specific event occurs—for example, a user specifying that 
a task is complete. At this point, Windows SharePoint Services commits the changes 
made in the previous Windows SharePoint Services workflow activities. Those changes 
are batched into a single SQL transaction, an approach that has two major advantages: 

■ Batching the changes is less performance intensive than committing each change 
as it occurs as a separate transaction. 

■ If any of the changes fail when committed, Windows SharePoint Services rolls 
back the changes to the previous commit point, which decreases the amount of 
work developers have to do when creating exception handlers and compensation 
handlers for Windows SharePoint Services workflow activities. 

When the event for which the workflow is waiting occurs, the workflow resumes run¬ 
ning and runs until another event is reached or the workflow ends, at which point Win¬ 
dows SharePoint Services commits any changes made by Windows SharePoint Services 
workflow activities that followed the last commit point. This continues until the work- 
flow reaches its conclusion or is stopped by the user. 

This approach can affect workflows in which Code activities are interspersed with Win¬ 
dows SharePoint Services-specific workflow activities. Although the write operations 
for the Windows SharePoint Services workflow activities are batched and not commit¬ 
ted until a commit point is reached, write operations that are included in Code activities 
are committed as they occur. Also, Code activities do not have the implicit rollback func¬ 
tionality of Windows SharePoint Services workflow activities. Exception and compensa¬ 
tion handlers must be written for those activities. 


Workflows in Action 

The sample SharePoint site illustrated in the examples in previous chapters is used by consult¬ 
ants for Litware, a fictitious company, to fill in a time sheet each day to summarize their activ¬ 
ities. The time sheet data is stored in a custom SharePoint list for later use. For example, at the 
end of every week, managers review the time sheets to approve or reject the hours submitted 
by each consultant. To facilitate this process, an approval process is followed for each weekly 
summary time sheet. In this section, we’ll demonstrate a workflow that creates a task assigned 
to a consultant’s manager and provides the manager with a form that he or she uses to accept 
or reject the time sheet. We’ll first illustrate the built-in approval workflow so that you can see 
some of the steps required to associate and configure a workflow with an item on a SharePoint 
site. After that, we’ll create our own approval workflow using Visual Studio 2005. 
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Associating and Activating SharePoint Workflows 

As mentioned earlier, Windows SharePoint Services provides several built-in workflow types. 
One of these is an approval workflow. As the result of user interaction with the workflow, a 
task is added to a task list on a SharePoint site. The approval workflow also provides Office 
InfoPath 2007 forms to facilitate interaction with the task. In this section, you’ll see how to 
attach an approval workflow to the Weekly Timesheets document library to facilitate manager 
approval of time sheets. 

Before you can use the approval workflow, you need to enable the Routing Workflows feature 
on the site collection. Open the site (http://ossl in our example) and navigate to the Site Set¬ 
tings page by clicking Site Settings on the Site Actions menu. Under Site Collection Adminis¬ 
tration, click Site Collection Features. Figure 7-1 shows the Site Collection Features page, 
which lists built-in workflows among the features. In the features list, find the Routing Work- 
flows feature and be sure that it is activated. 


iHSiaSZSEK 

>j*e L<k »ew tffvcrtes loots 

t tntrrrwt 

i * 

On* • O - a) Jd 


narch F avert rs /• * r ^ 



|£) htft/jOKl/ layouts/Menegei eatcres asc* VSCCM-Ste 

3 i3 r ' 

inks 

" 

Tamil Stto 


Welcome Lilnareliii. AdmimsUatur * I Hr Sits 1 M 

Links • | Help | Send Feedback 

* 

|***Team Site 




Hune 





G) 

Site Collection Features 








s2> 

Content 1 ype Definition 

Active 




(XX) content type defnCcns 

oeactrvate | 





Dispositton Approval Workflow 

Active 





jysWtri workflow for genetebng « asposfcon aecroval task. 

Deactivate | 




v3) 

Collect Signatures WoiKtow 

C.sther'. njWitei nrrvtnd to crtrtirtr an Ctflre donewni. 

Orarttvate | 





I teM Definition 

Active 




OOtNddrfMfem 

Oearttvate | 





Issue 1 tacking workflow 

Arttve 




Use this workflow to tr ark Issues. 

Oearttvate | 





excel Services Me 1 eoture 

Active 


- 1 


A/i*s <e level Mrrnsoft Cither Fxrrl Srrvtres Foatirrs to the Windows SharePoM SrrWres ftatwwrrk 

Oearttvate | 





Rmitmo Workflows 

Workflows rKv seed a dorimert for fnedhark nr Approval. 

Active 

Oearttvate 1 




^> 

Translation workflow 

Active 




TNs wort flow wd nr.tr plarrtv*1er don wonts and send Ihrm to transistors. 

Oearttvate | 





Wrh Part Adder default groups 

Inactive 


zl 

©Done 



k-J local ntranet 


tf.'Slati| ^ & 

| S»e r olrrtlnn Featur~ 

0 9:56 AM 


Figure 7-1 To use a built-in workflow, you must activate the workflow on the site collection. 

For this example, we also need to create a task list to store workflow-related tasks. To do this, 
we open the site’s complete content list using the View All Site Content link and create the list, 
choosing Tasks as the list type. 
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Now that the preliminary work is done, we can associate the approval workflow with the 
Weekly Timesheet document library. After opening the document library, we use the Docu¬ 
ment Library Settings page to open the page shown in Figure 7-2, which lets us associate the 
workflow with the library. On the page, we select the Approval workflow template, name the 
workflow TimeSheetApproval, and select the task list we created to store the workflow tasks. 
In this example we also indicate under Ffistory List to create a new workflow history list to 
store the history of the workflow. 
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Figure 7-2 This page is used to define attributes when adding a workflow to a list or library. 

After clicking Next on the page shown in Figure 7-2, we see the page shown in Figure 7-3. On 
this page, we can configure settings related to the approval process. For our purposes, we’re 
interested only in the Approvers text box. In it we enter litwareinc\administrator so that the 
administrator must approve each time sheet document. We then click OK to complete the 
steps for setting up the workflow. Now we can test the approval process. 

In the Weekly Timesheets document library, we select the Workflows menu item from one of 
the time sheet documents, and then start the workflow by clicking the TimeSheetApproval 
link under Start A New Workflow, shown in Figure 7-4. 




Creating Workflows: The Missing Piece of Office Productivity 


131 


1 f net nnilrr Workflow Mlrmsnft Intrrnrt Fstpinrer 

-IffJxJ 

!> tdt view i pycrttes looks llekp 

_J & 

Bntt * - ] c v.vrh F avert rs • . Q ^ 


AjJ*nss |^1 http:/,loss!) layoOts/tdtWrifltt’.asp-:cUSt-fjWjtM ♦-A JW-40W -VfjV-VJfS&rM 1IC> 

3 fl ce> ,|nk< ” 


Welcome Litvrarelru, i 


I Help | Send Feedback 


l***Team Site 

Homo_ 




Customize "TimeSheetApproval”: Weekly Timesheets 


| Caned | 


Workflow tasks 

jpeefy few tasks ve routed to partKparts and whether to 
alow tasks to he dHr^rtod nr f pvtirpvfr ran rrqurst 
charges be made to the document poor to fnehng thee 
task*. 


Assign tasks to: 

^ Al pvhrlpanrs sm*.w-flidy (jvrnW) 

** Ooe perbepert at a woe (serial) 

Alow wrrkflnw partklpanrt to: 

& WepaOuri task* to anutlisr person 
I* Request a change hrfnrr rmrflntlng the tr 


Del ault World hm Start Values 

Seedy Uie iWad vak*s Out Urs wcrklkm wl use rdwn t type the names cf people you wi 
a started v ou can cpt to lock the kst of csrbclpsrits so that t started. Add names m the wrtrr 
catrX be dumped by Uw person staring tie werkfkaw. serial workflows). 


| |ktwaremcSadnn»stryor~ 


□ «r| 


P Alrw rhviges tn partlr^cvits when Ifls wrrkftsw is started, 
type a message to ndude *nth your request: 


Figure 7-3 This page is used to define aspects of the approval process managed by the workflow. 
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Figure 7-4 Users initiate a workflow using a menu command that opens this page. 
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The initialization page shown in Figure 7-5 allows us to modify the initialization parameters 
set when we created the workflow. In this case, we won’t override any of these settings, so we 
simply click Start to initiate the workflow. 
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Figure 7-5 The page that starts the workflow 

As you can see in Figure 7-6, the workflow has created a task for the Litwarelnc Administrator 
to resolve. 

The next step in the workflow is to complete the task so that the workflow can continue. We 
do that in the Tasks list by editing the properties of the task. On the approval form, shown in 
Figure 7-7, an approver can enter comments and approve or reject the time sheet. 
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Figure 7-7 A manager uses this form to approve or reject the time sheet. 
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After approving the time sheet, the last step is to verify that the workflow was successfully 
completed and that the time sheet has been approved. We can see in Figure 7-8, which shows 
the Weekly Timesheets document library, that the TimeSheetApproval column for the docu¬ 
ment we approved is set to Completed. 



Figure 7-8 The status of a workflow is displayed for the item in a document library. 


Creating a Human Workflow in Visual Studio 2005 

Even though Windows SharePoint Services provides several workflow solutions, from time to 
time you’ll need more functionality than is provided by the built-in routines. In these cases, 
developers can create custom workflow solutions as well as custom Office InfoPath 2007 
forms for managing workflow initialization and task completion. In this section, you’ll see 
how to create a custom approval workflow and interactive forms using Visual Studio 2005 
and Office InfoPath 2007. We’ll start by creating a project (named CustomApproval) in Visual 
Studio 2005, basing the project on the SharePoint Sequential Workflow Library template. 
Visual Studio fills out the project with initial references, an XML file, and a preliminary class 
named Workflowl.es. Figure 7-9 shows the Visual Studio window with Workflowl.es open in 
design view and the default onWorkflowActivatedl activity already in place. 
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Figure 7-9 The initial project window for a SharePoint Sequential Workflow Library template 
project 

The first step in implementing the workflow is to retrieve information such as the name of the 
manager who needs to approve the document and any comments associated with the docu¬ 
ment approval process. To gather this information we add three member fields to the 
Workflowl.es class. (To view the code for Workflowl.es, you can right-click Workflowl.es 
and select View Code.) The member fields we add, all strings, are named user , comments, and 
taskStatus. 

Next we switch Workflowl.es back to design mode and create an event handler for this initial 
activity by right-clicking the representation of onWorkflowActivated 1 and selecting Generate 
Handlers. We implement the handler by accessing the workflowProperties.CreationData collec¬ 
tion to access the User and Comments values and store them in the member fields. Here’s the 
code for the initial fields and the handler: 

public string user; 
public string comments; 
public string taskStatus; 

private void onworkflowActivatedl_lnvoked(object sender, EventArgs e) 

{ 

// retrieve the creation data 

user = workflowProperties .CreationData["user"]-ToStringO ; 
comments = workflowProperties.CreationData["Comments"] .ToStringO ; 

} 
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Next well create a step in the workflow by using the CreateTask activity. We start by creating 
several member fields in the Workflowl.es class to store information about the task’s prop¬ 
erties before and after editing. These fields are used to retrieve the results of the task’s 
completion. 

public Guid tasklD = default(System.Guid); 

public Microsoft.SharePoint.workflow.SPWorkflowTaskProperties taskproperties = 
new Microsoft.SharePoint.workflow.SPWorkflowTaskPropertiesQ ; 
pub!ic Microsoft.Sharepoint.workflow.SPWorkflowTaskProperties 
taskBeforeProperties = 

new Microsoft.SharePoint.workflow.SPWorkflowTaskPropertiesO ; 
pub!ic Microsoft.Sharepoint.workflow.SPWorkflowTaskProperties 
taskAfterProperties = 

new Microsoft.SharePoint.workflow.SPWorkflowTaskPropertiesO ; 
public System.workflow.Runtime.Messaging.CorrelationReference 
taskReferenceObject = 

new System.workflow.Runtime.Messaging.CorrelationReferenceO ; 

We switch Workflowl.es to design mode again and drag a CreateTask activity onto the canvas 
after the activation activity, as shown in Figure 7-10. 


Ute L<fc »ew »o*ect LM*3 Uebug Wfirtftow Dflta left I«b uxwrtrrty Ueto 



Figure 7-10 You can build the stages of a workflow by dragging activities from the toolbox. 

Now we need to use the properties pane and set several properties for the CreateTask activity. 
We set its CorrelationRejerence property to /Workflowl.taskReferenceObject, its Taskld prop¬ 
erty to /Workflowl.taskld, and its TaskProperties property to /Workflowl.taskProperties. 
These values are used by the activity to manage the lifetime of the workflow and to provide 
parameters for the task’s creation. 



Creating Workflows: The Missing Piece of Office Productivity 


137 


Finally we need to populate the properties of the task by using the taskProperties variable. To 
access this code, we right-click createTaskl and click Generate Flandlers. The only property 
that is required is taskID, which was set in the designer. The ExtendedProperties property is 
used to send information to and from the Office InfoPath 2007 forms. 

private void createTaskl_Methodlnvokingfobject sender, EventArgs e) 

{ 

// initialize the task ID 
taskID = Guid.NewGuidO; 

// populate the properties of the task 
taskProperties.AssignedTo = user; 

taskproperties.Description = "Approve the document."; 
taskProperties.Title = "Timesheet Approval"; 

// populate the type of the form and extended properties 

taskproperties.TaskType = 0; // This is used to map tasks to InfoPath forms 
taskProperties.ExtendedProperties["Comments"] = comments; 

} 

The previous step created a new task. The next step is to wait for the task to change and 
store the results of the change. We open Workflowl.es in design mode and drag an 
OnTaskChanged activity to the workflow canvas, placing it after the createTaskl activity. We 
set its CorrelationRejerence property to /Workflowl.taskReferenceObject, its Taskld property 
to /Workflowl.taskld, its BeforeProperties property to /Workflowl.taskBeforeProperties, and 
its AfterProperties property to/Workflowl.taskAfterProperties. 

Now we need to write the code associated with the OnTaskChanged handler that will retrieve 
the status value from AfterProperties and store it in the member variable taskStatus. 

private void onTaskChangedl_lnvoked(object sender, EventArgs e) 

{ 

// retrieve the TaskStatus property from the infopath form 

taskStatus = this.taskAfterProperties.ExtendedProperties["TaskStatus"].ToString(); 

} 

The last step in defining the workflow is to complete the task and set its status to the Task- 
Status value retrieved in the previous step. Again we open Workflowl.es in design mode. This 
time we drag a CompleteTask activity onto the canvas and place it after the OnTaskChanged 1 
activity. For this activity, we set the CorrelationRejerence property to /Workflowl.taskRefer¬ 
enceObject, the Taskld property to /Workflowl.taskld, and the TaskOutcome property to 
/Workflowl.taskStatus. The TaskOutcome property is the text value that is used when setting 
the status value of the completed task. 

Now that the design and coding of the workflow is complete, we need to sign and build the 
workflow assembly. To sign the assembly, we navigate to the Signing tab in the project prop¬ 
erties window, select the Sign The Assembly check box, and browse to the .snk file to use— 
CustomApproval.snk in this example. 
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Next we need to create the Office InfoPath 2007 forms that will be used by the workflow. The 
first form will be used to retrieve the user name of the manager who is assigned the approval 
task. The form has two fields, User and Comments, that are tied to appropriate data sources 
for receiving data. (For the purposes of the example, we used XML files.) The form also 
includes a text box and a button that is used to submit the form to Windows SharePoint 
Services and then close the form. Figure 7-11 shows the initialization form, named Custom- 
ApprovalAssoc. 



Figure 7-11 The first of the three Office InfoPath 2007 forms created for the custom workflow 

Next we’ll define the form that is displayed when a new instance of the workflow is started. 
We can base this form on the previous form so that the primary data source will have the same 
namespace in both forms. We modified this form by changing the text box label from Man¬ 
ager’s User Name to Comments and changing the binding of the text box to the Comments 
data source field. This form is saved as CustomApprovallnit. 

The last form we create is used when acting on the approval task. In this form, the manager is 
presented with any comments entered in the CustomApprovallnit form and two buttons—one 
to click to approve the document and another for cases when the document is rejected. The 
design of this form includes a field named TaskStatus and two XML data connections for 
receiving data. (The Comments text box at the top of the form is bound to a field named 
ows_metaInfo_Comments in one of the data sources.) The Accept and Reject buttons set the 
value of the TaskStatus field, submit the data to Windows SharePoint Services, and then close 
the form. Figure 7-12 shows the approval form. 
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Figure 7-12 The task approval form 


The next step is to define a feature that will install the workflow. The Visual Studio project 
provides a basic Feature.xml file that you can use for this purpose. The information you need 
to add to the file includes a GUID for the workflow, which you can generate by clicking the 
Create Guid command on the Tools menu in Visual Studio. For the RegisterForms value for 
this example, we use Forms/*.xsn. Flere is the XML from the file: 


<?xml version="l,0" encoding="utf-8" ?> 

<!— _lcid="1033" _version="12.0.3111" _dal="l" --> 
<!— _LocalBinding --> 


<!— Customize the text in square brackets. 

Remove brackets when filling in, e.g. 

Id="[UNIQUE GUID]" ==> Id="328B9FAF-0E29-46bl-92B3-7lF7DlD67761" --> 


<Feature Id="FDl30413-76CE-475e-9160-CB5C75116165" 

Title="Custom Timesheet Approval" 

Description="Custom Timesheet Approval workflow" 
version="12.0.0.0" 

Scope="Site" 

ReceiverAssembly="Microsoft.Office.workflow.Feature, version=12.0.0.0, 
Culture=neutral, PublickeyToken=71e9bcellle9429c" 

ReceiverClass="Microsoft.Office.workflow.Feature.workflowFeatureReceiver" 
xmlns="http://schemas.microsoft.com/sharepoint/"> 

<ElementManifests> 

<ElementManifest Location="workflow.xml" /> 

</ElementManifests> 

<properties> 

<property Key="GloballyAvailable" value="true" /> 
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<!-- value for RegisterForms key indicates the path to the forms relative to 
feature file location --> 

<!-- if you don't have forms, use *.xsn --> 

<property Key="RegisterForms" value="Forms/*.xsn" /> 

</properties> 

</Feature> 

Next we open the Workflow.xml file, which is also provided by Visual Studio, and fill 
in the first portion of its template. (You’ll need to check the public key token of the 
Microsoft. Office. Workflow.Feature assembly deployed in the Global Assembly Cache (GAC) 
when working with the file yourself.) We populate the MetaData section with URNs for the 
three Office InfoPath 2007 forms we created earlier. To find the URN, open the form in Office 
InfoPath 2007 in design mode and choose Properties from the File menu. 

<?xml version="1.0" encoding="utf-8" ?> 

<!— _lcid="1033" _version="12.0.3015" _dal="l" --> 

<!— _LocalBinding —> 

<!— Customize the text in square brackets. 

Remove brackets when filling in, e.g. 

Id="[UNIQUE GUID]" ==> Id="328B9FAF-0E29-46bl-92B3-7lF7DlD67761" --> 

<Elements xmlns="http://schemas.microsoft.com/sharepoint/"> 

<workflow 

Name="Custom Timesheet Approval" 

Description="Custom Timesheet Approval workflow" 
Id="E6D98FE0-E332-4471-AFDE-2088lAFCAAD5" 

CodeBesideClass="CustomApproval.workflowl" 

CodeBesideAssembly="CustomApproval, version=3.0.0.0, Culture=neutral, 

PublickeyToken=6479e6da8b088665" 

Associationu rl="_1ayouts/Cstwrkf1 IP.aspx"> 

<Categories/> 

<MetaData> 

<Association_FormURN>urn:schemas-mi crosoft- 

com:office:infopath:CustomApprovalAssoc:-myxSD-2006-01-02T01-28- 
35</Association_FormURN> 

<lnstantiation_FormURN>urn:schemas-microsoft- 

com:office:infopath:CustomApprovalinit:-myxSD-2006-01-02T01-28- 

35</lnstantiation_FormURN> 

<TaskO_FormURN>urn:schemas-microsoft- 

com:office:infopath:CustomApprovalTask:-myxSD-2006-01-02T02-08- 
14</TaskO_FormURN> 

<StatusPageurl>_layouts/wrkstat.aspx</StatusPageurl> 

</MetaData> 

</workflow> 

</Elements> 

The last step in creating the feature is to update the Install.bat file that Visual Studio 2005 
provides when you create the workflow project. You can use this file to install and activate the 
feature. Flere is the file as Visual Studio provides it. 
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©echo off 
if .%!.==. . ( 
goto usage 
) 

echo Copying the feature... 
echo. 

rd /s /q "%CommonProgramFiles%\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES\ 
[FEATURE NAME]" 

mkdir "%CommonProgramFiles%\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES\ 
[FEATURE NAME]” 

copy /Y [feature xml file name] "%CommonProgramFi 1es%\Microsoft Shared\web 
server extensions\12 \TEMPLATE\FEATURES\[feature name]\" 

copy /Y [workflow xml FILE name] "%CommonProgramFiies%\Microsoft Shared\web 
server extensions\12 \TEMPLATE\FEATURES\[feature name]\" 
xcopy /s /Y [FORMS, e.g. *.xsn or Forms\*.xsn] "%programfiles%\Common 
Fiies\Microsoft Shared\web server extension s\12\template\features\[feature 
name]\[FORMS directory if any; should match the location specified in your 
feature.xml under RegisterForms]\" 


echo. 

echo Adding assemblies to the GAC... 
echo. 

"%programfiles%\Microsoft visual Studio 8\SDK\v2.0\Bin\gacutil.exe" -uf [dll 
name (no extension, e.g. HelloworkFlow)] 

"%programfiles%\Microsoft visual Studio 8\SDK\v2.0\Bin\gacutil.exe" -if [path 
TO dll relative TO THIS file, e.g. bin\Debug\HelloworkFlow.dll] 

echo. 

echo Activating the feature... 
echo. 

pushd %programfi1es%\common files\microsoft shared\web server extensions\12\bin 
stsadm -o deactivatefeature -filename [feature name\feature xml file name, 
e.g. Helloworkflow\feature.xml] -url %1 

stsadm -o uninstallfeature -filename [feature name\feature xml file name, e.g. 
He! 1 oworkf1ow\featu re.xml] 


stsadm -o installfeature -filename [feature name\feature xml file name, e.g. 
Hel 1 oworkf1ow\featu re.xml] 

stsadm -o activatefeature -filename [feature name\feature xml file name, e.g. 
Helloworkflow\feature.xml] -url %1 


echo Doing an iisreset... 

echo. 

popd 

i isreset 


goto end 
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: usage 
echo. 

echo usage: install A<url of ServerA> 
echo i.e. install http://myserver 
echo. 

: end 

You execute Install.bat with the command line parameter with the URL to your site, which 
will register the assembly in the GAC, uninstall, reinstall, and finally activate your workflow 
feature. You could now follow the steps shown earlier in the chapter to associate the custom 
workflow with the Weekly Timesheet document library, configure the workflow so that the 
Litwarelnc Administrator must approve the document, and then run and test the workflow. 


Note You can implement conditional branching in a workflow. For example, if a time sheet 
is approved, the manager needs to be sure the consultant is paid. You could extend the 
approval workflow by using the Windows Workflow If-Else activity to create a new task for the 
manager only if TaskStatus is set to Accepted. 
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Microsoft Office SharePoint Server 2007 Excel Services, new server technology that ships with 
the 2007 Microsoft Office system, supports loading, calculating, and rendering Excel work¬ 
books on servers. Excel Services has two primary interfaces: a Web-based user interface that 
enables users to view workbooks in a browser, and a Web services interface for programmatic 
access to the data and logic in workbooks. Excel Services, which requires Microsoft Office 
SharePoint Server 2007, provides the following capabilities: 

■ Allows browser-based access to workbooks 

■ Incorporates workbooks in portals and on dashboards 

■ Controls access to workbooks for either regulatory and audit concerns or to protect 
intellectual property in the workbooks 

■ Eliminates “multiple versions of the truth”; in other words, Excel Services makes it 
unnecessary for users to maintain separate copies of the same workbook, which are 
often out of sync 

■ Uses servers to offload long-running calculations from desktop computers 

■ Enables logic and business models built in Excel to be used in other applications with¬ 
out having to develop the logic or business models again in a programming language 

Excel Services is built on Office SharePoint Server 2007, which means, for example, that when 
a user saves a workbook to Excel Services, he or she saves it to a SharePoint document library 
and can then make use of SharePoint document library features. A whole range of additional 
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features in SharePoint and Excel Services together provide tools to help organizations and 
users share, manage, and control workbooks. These features include workflows, versioning, 
auditing, and taking snapshots of workbooks at specific points in time. 

This chapter introduces some of the key concepts and practices of Excel Services. We’ll look 
at the scenarios for which Excel Services can be used, its architecture, mechanisms for control¬ 
ling who can access a workbook, and how users can interact with workbooks in the browser. 
We’ll also review methods and other elements of the Web services interface. Then we’ll dem¬ 
onstrate how to work with Excel Services and a SharePoint site, how to incorporate Excel for¬ 
mulas in an application, and how to create a user-defined function (UDF) that you can use 
with Excel Services. 

Key Scenarios for Excel Services 

Microsoft targeted three scenarios for the initial release of Excel Services: 

■ Sharing workbooks through the browser 

■ Building business intelligence (BI) dashboards 

■ Reusing the logic encapsulated in Excel workbooks in custom applications 

In the following sections, we’ll look at each of these scenarios in more detail, starting with 
sharing workbooks and issues related to controlling and managing workbooks. 

Sharing Workbooks Through a Browser 

Certain types of workbooks—those that contain important business information or logic, 
require intensive calculation, or are shared with customers or partners—don’t easily lend 
themselves to current methods of sharing workbooks, such as e-mail or file shares. For exam¬ 
ple, sharing through e-mail tends to multiply the number of copies of a workbook. It’s easy for 
users who receive the file to modify their personal copies, which results in more than one 
copy of the data. Which version is accurate? 

It is also difficult for workbook authors to protect parts of their work—for example, key logic, 
business modeling, or data that is considered confidential or proprietary intellectual prop¬ 
erty-while sharing other parts of the workbook, such as the completed analysis they want a 
client to see. Finally, large workbooks that require intensive calculation are not well suited for 
distribution by e-mail. Every user who opens the file has to wait for the workbook to down¬ 
load and the calculations to run before they can continue with their work. 

Excel Services provides users with means to handle these and other issues related to sharing 
workbooks. Using Excel 2007, workbook authors can save their files to a SharePoint docu¬ 
ment library and give other users browser-based access to the server-calculated version of that 
workbook. When a user accesses the workbook, Excel Services loads the workbook, refreshes 
external data when necessary, runs necessary calculations, and sends the resulting output to 
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the browser. The workbook is rendered using only DHTML. No ActiveX control is required, 
and no client installation of Office Excel 2007 is necessary. Users view the latest version of the 
workbook, and they can interact with its data in the browser. Moreover, a workbook author 
can restrict access to specific sheets or cell ranges in the workbook, thus hiding intellectual 
property from people who need to see only the results. A user accessing the file in the browser 
sees only cell values and not the underlying formulas. If multiple users are viewing the same 
workbook, it is loaded and calculated only once by the server, saving the network bandwidth 
and lessening the wait time for long-running calculations. Finally, workbook access can be 
logged and audited. Overall, these capabilities provide a powerful means for sharing work¬ 
book via the browser in a controlled and secure way. 



Note Excel Services does load balance separate workbook calculations across multiple serv¬ 
ers and calculates more than one workbook on a server (each request runs on a different 
thread). Excel Services does not, however, break out a single workbook across multiple servers. 
This design is optimized for scaling to large numbers of workbooks and requests; for example, 
many users viewing a dashboard with data from a number of workbooks on it, or programmat¬ 
ically running a large parametric sweep of a workbook or group of workbooks. 

The upcoming Microsoft Windows Compute Cluster Server 2003 complements Excel Services' 
interactive end-user scenarios by providing scalable, reliable, batch workbook processing. 
Compute Cluster enables computation-intensive applications to scale their performance and 
achieve high availability using farms of 64-bit servers. Compute Cluster capabilities can be eas¬ 
ily integrated into an application using a .NET or DCOM object model. For example, a Web Part 
can be programmatically connected to a Compute Cluster job scheduler that distributes a pro¬ 
cessing load over a number of compute nodes, each running a separate instance of the Excel 
Services engine. For more information about Microsoft Windows Compute Cluster Server 
2003, see www.microsoft.com/windowsserver2003/ccs/default.mspx. 


Building Business Intelligence Dashboards 

Business intelligence is one of the key areas of focus for Office Excel 2007 and Excel Services. 
The browser-based sharing of workbooks described in the previous section is part of that 
effort. Business people such as financial analysts, business planners, and engineers who work 
with data in Excel workbooks can’t easily reuse and share that data in a portal or on a dash¬ 
board. The integration of Excel Services with Windows SharePoint Services and Office Share- 
Point Server 2007, however, allows all sorts of users to build Web solutions that contain live 
and interactive data without using any code, as shown in Figure 8-1 on the next page. 

Let’s look at the pieces that could be included on a dashboard and how it would be created. 

■ Office SharePoint Server 2007 The dashboard is built using Windows SharePoint 
Services, and its format is consistent with the rest of the SharePoint site it belongs to. 
Because the concept of a dashboard (a page containing a set of SharePoint Web Parts) is 
native to the SharePoint platform, it is simple for users to create dashboards that look 
like the rest of their intranet site. 
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■ Excel Services Two of the Web Parts on the dashboard are provided by Excel Ser¬ 
vices; in this example, a table and chart are contained within a workbook, but these 
could also be formulas, PivotTables, and so on. In the context of a dashboard, however, 
users can configure Excel Services to show only a portion of the workbook (a “sum¬ 
mary” view). The author can also configure the level of interactivity available for a dash¬ 
board. Finally, because Excel Services is just showing a workbook, the creator of the 
dashboard can make use of his or her knowledge of Excel to create that workbook and 
format it without writing any custom code to access external data, perform calculations, 
format the results, or provide interactivity. 

■ Key Performance Indicators One of the Web Parts on the dashboard is a Key Perfor¬ 
mance Indicator (KPI) List Web Part. This Web Part is part of SharePoint, not Excel Ser¬ 
vices. A KPI Web Part provides a highly visual display of data that allows users to get a 
sense of the status of important factors in their work. The data can come from sources 
such as a manually maintained Excel worksheet or an enterprise database. 

■ SharePoint Filters The final set of Web Parts on this dashboard are Filter parts, which 
are also SharePoint Web Parts, not from Excel Services. These Web Parts can be hooked 
up without code to other parts on the page, enabling users to filter everything they see 
on the page. For example, if a user named Beth wanted to see only her support calls for 
ProductA during FY04, she would enter those criteria and click Apply Filters. All the 
content on the dashboard (chart, table, KPIs) would update accordingly. Filters can be 
set up to allow users to pick from a predetermined set of values; enter a date, number, or 
string; filter on the user viewing the dashboard; filter on values in an external database; 
and the like. 
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Figure 8-1 A business intelligence dashboard built without code using Excel Services 
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How is this dashboard created? A user with the appropriate SharePoint permissions can cre¬ 
ate a dashboard with just a few clicks. They can choose which Web Parts (there are many 
more than the few just mentioned) they want to display on the dashboard, as well as where 
they want those parts displayed. After choosing the Web Parts to include on the dashboard, 
the user can configure the dashboard using a Web browser, setting up which workbook data 
is shown (and how), what KPIs are shown in the KPI list, and what filters should be available, 
for example. 

Reusing the Logic Encapsulated in Excel Workbooks 

In addition to a browser-based interface to the server, Excel Services provides a Web service 
interface. The same workbook that is published by its author can be accessed programmati¬ 
cally by any application that can communicate through Web services. The calling application 
can change values, calculate formulas in the workbook, and retrieve some or all of the 
updated workbook using the Web service interface (subject, of course, to security permis¬ 
sions). This capability opens a range of interesting possibilities and solutions for using Excel 
and Excel Services. 

Today, developers or other users of spreadsheets need to rewrite the logic represented in 
them in code to support running in a server-grade environment. Excel Services lets the logic 
be retained and updated when necessary in a workbook and used to its full effect in the con¬ 
text of an application. This combination of effort provides users with the best of both worlds— 
easier and more effective modeling in Excel, as compared to custom code, together with appli¬ 
cation integration, scalability, and manageability. 


Multi-User Editing of Workbooks 

Excel Services does not attempt to address the scenario of multiple users who want to 
jointly author a workbook in real time and see each other’s edits. Excel Services allows 
more than one user to open and interact with a workbook at the same time, but each 
user has his or her own session. If a user interacts with the workbook (for example, by 
setting a filter on a PivotTable), other users do not see those changes. The changes a user 
makes are not saved to the original file. 

The server storing the workbook opens the file as read-only, and each user has his or her 
own session state in the server’s memory. A workbook is loaded only once in server 
memory no matter how many users are accessing it. Each user’s session maintains the 
specific interactions (for example, filters) that the user has performed and how the 
workbook results should be calculated and returned to that user. This behavior is the 
same whether calling the workbook through Web services or accessing it through the 
Web-based user interface. 
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Excel Services Architecture Overview 

As mentioned previously, Excel Services is part of Office SharePoint Server 2007. Excel 
Services has three components: Excel Web Access, Excel Web Services, and Excel Calculation 
Services. 

■ Excel Web Access is a SharePoint Web Part that performs the rendering (in this case, 
creating the HTML) of Excel workbooks on a Web page. You can use this Web Part as 
you would any other Web Part in SharePoint to create a wide range of pages. 

■ Excel Web Services provides programmatic access to the logic and data in a workbook. 
This component is a Web service hosted in SharePoint. You can use methods in this 
Web service to develop applications that incorporate calculations performed by Excel 
Services and to automate the updating of Excel workbooks. 

■ Excel Calculation Services is the component that loads the workbooks, calculates them, 
refreshes external data, and maintains session state for interactivity. This component is 
at the heart of Excel Services. 

Additionally, Excel Services makes use of a proxy internally to handle the communication 
between the components on the Web front end and the application server in multiple-server 
configurations. This proxy also handles load balancing in case there are multiple application 
servers in your installation. 

In the simplest configuration, the three components that make up Excel Services would run 
on the same computer; however, in most production environments with a significant number 
of users, the components on the Web front end and the application server would be on differ¬ 
ent computers. 

Security 

Excel Services uses the security infrastructure provided by Windows SharePoint Services. 
Excel Services uses Windows SharePoint Services for authentication (who can log onto the 
server) as well as authorization (who has access to which workbook and the type of access: 
read, write, view only, and so on). The reliance on the Windows SharePoint Services security 
infrastructure provides a strong security environment for protecting workbooks. 

Performance and Scalability 

Excel Services is optimized for scenarios in which multiple users access the same worksheets. 
This optimization is achieved by caching at multiple levels so that collective performance for 
a group of users is improved by caching the workbooks as well as any external data queried 
by the workbooks. These operations are transparent to an end user except for the response 
time. (Cached results are shared only between users who have the same rights.) 
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Controlling Visible Information and Interacting 
with Workbooks 

When a workbook is published to Excel Services, the entire workbook is saved to the server 
so that data can be refreshed or calculations run. The workbook author can, however, control 
which parts of the workbook are visible when a user views the file in the browser or it is 
accessed through the Excel Services Web services API. The three choices for controlling how 
a workbook is viewed on the server are 


■ The entire workbook (the default setting). 

■ A subset of sheets (as many or as few as you want). This approach is useful when you 
have workbooks that contain lots of behind-the-scenes sheets that hold intermediate cal¬ 
culations, source data, and so on, but only a few sheets that you want users to see. If an 
author needs to make changes to the workbook over time, however, he or she still can 
use all the features in Office Excel 2007 and can see the entire workbook without having 
to unhide sheets. 

■ A set of named items, such as named ranges, charts, tables, PivotTables, and Pivot- 
Charts. This mode is called Named Object view. In this view, users can select the items 
they want to see from a drop-down list in the browser. Items are displayed one at a time, 
which simplifies setting up a dashboard. Even though only a single item is shown at a 
time, the entire workbook is loaded in Excel Services, which means that the visible 
objects can be refreshed and are interactive. 


Defining Parameters 

Users are able to interact with a workbook in the browser, but they will not be able to directly 
edit cells in the grid. Instead, workbook authors can specify parameters as part of the process 
of publishing a workbook to Excel Services. Parameters let an author expose specific cells 
whose values a user can then change when working with the data. Excel Services provides a 
built-in task pane for changing the values of parameters. After the value of a parameter has 
been changed, the workbook calculates new values and the user sees the results in the 
browser. 


Note that not all cells can be exposed as parameters. Here are the restrictions: 

■ The parameter must be a single cell and cannot be a range. 

■ The cell must not contain a formula. 

■ The cell must be a regular workbook cell, not a cell in a PivotTable, table, chart, and 
so on. 


The cell must have a defined name. 
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Interacting with Workbooks in the Browser 

Users can interact with workbooks in the browser in a number of ways: 

■ View workbooks in a browser 

■ Navigate within workbooks 

■ Sort, filter, and perform other operations on the data in workbooks 

■ Change parameters to facilitate what-if analysis in the workbooks 

Features related to interactivity are generally grouped into three areas: worksheets, tables, and 
PivotTables. Although the level of interactivity does not include full authoring of workbooks 
in the browser, users with appropriate permission can open a workbook in Office Excel 2007 
and have the complete range of Excel’s features at their behest. In situations in which interac¬ 
tivity needs to be controlled—for example, if you want to display some data using a PivotTable 
but don’t want users to be able to change the view—interactivity can be turned off. You can, for 
instance, allow users to sort but not filter, to interact with tables but not with PivotTables, and 
so on. 

Interactivity with Worksheets 

Excel Services supports the same layout and formatting capabilities as does Office Excel 2007. 
To users, a worksheet viewed in Office Excel 2007 will look the same as the worksheet viewed 
in a browser (within the constraints of HTML). The look of a worksheet includes familiar for¬ 
matting as well as features new to Office Excel 2007, such as data bars, color scales, table 
styles, and others. 

Only one section of a worksheet is served up by Excel Services at one time. This limitation is 
a performance optimization, as less HTML needs to be served up to the client. The number of 
rows and columns can be configured. The default values are 75 rows and 20 columns. Paging 
controls allow a user to move between sections. 

Users will also be able to page between worksheets (using tabs as in Excel), expand and col¬ 
lapse outlining, set parameters, refresh external data and calculate the worksheet, and find 
values within the worksheet. (The Find feature will search for values in the entire worksheet, 
even the parts that are outside the current section.) 

Interactivity with Tables and AutoFilters 

If a workbook contains a table or autofilters, users will be able to set and update sorts and fil¬ 
ters. Specifically, users will be able to sort data in ascending or descending order, use a multi¬ 
select or Top 10 filter, set quick filters (“Above Average,” “Below Average,” “Contains,” “Last 
Month,” and so forth), or set custom filters (“Less Than,” “Contains,” and so on). 
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Interactivity with PivotTables 

If a workbook contains a PivotTable, users can interact with the PivotTable within the 
browser, including expanding and collapsing levels, sorting in ascending or descending 
order, applying a multiselect or Top 10 filter, setting quick filters, or setting custom filters. 

Building Applications with Excel Web Services 

One of the main purposes of Excel Services is to enable the logic encapsulated in Excel work¬ 
books to be used in custom applications. Having this capability means having access to work¬ 
books and their contents on the server through Web services in a manner that’s scalable and 
manageable. 

As mentioned earlier in the section about Excel Services architecture, Excel Calculation Ser¬ 
vices is the engine of Excel Services; it is the component that loads and calculates workbooks. 
In situations in which users interact with a workbook in the browser, Excel Calculation Ser¬ 
vices loads and calculates a workbook and then hands it off to the Excel Web Access compo¬ 
nent, which produces the HTML that is rendered in the browser. Developers can also use 
Excel Calculation Services without interacting with the Excel Web Access component. Specif¬ 
ically, a Web service API sits on top of Excel Calculation Services so that developers can call 
server-side workbooks directly from their own applications. For example, developers can 
write code that opens a workbook on a server, sets cells and ranges to specific values, controls 
an external data refresh and workbook calculation, and then retrieves values from the calcu¬ 
lated workbook or retrieves the workbook in its entirety. 

Excel Web Services enables many possibilities. In one scenario, a business expert who 
authors a workbook can now maintain the model in Excel; an administrator can protect that 
model on the server using the appropriate set of users, roles, permissions, and a firewall; and 
a developer can call Excel Web Services to incorporate the logic of the model into the opera¬ 
tions of a custom solution. A variation on this would be to provide a custom user interface to 
Excel-based server applications that use Excel Web Services to interact with a server-side cal¬ 
culation session. 

Another scenario in which Excel Web Services will play a role is automating workbook 
updates on servers. This capability works especially well in combination with the new Open 
XML file format, which greatly simplifies the task of programmatically creating an Excel file 
from scratch or by using a template. After a file has been created, it often needs to be calcu¬ 
lated; for example, external data feeds need to be updated. It is straightforward for developers 
to write code that uses Excel Web Services to perform these operations and then retrieves an 
up-to-date copy of the calculated file and saves it back to the server or delivers it to any other 
destination. 

In brief, you can write code that can start a session with Excel Calculation Services, set values 
in cells and ranges, process the workbook, and get calculated values or the entire workbook 
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back to use within your application. The following list describes some methods and proper¬ 
ties of Excel Web Services. You’ll see some sample code later in the chapter. 

■ GetApiVersion gets a version string of the installed Web service API build. 

■ sessionld = OpenWorkbook opens a server-side calculation session. The method takes a 
workbook file path and a few other arguments and returns a sessionld. 

■ GetSessionlnformation gets a few properties of the server session, primarily the language 
context of the session. 

■ SetCell sets a value in a cell on one of the workbook’s sheets. Two versions of this 
method exist: one takes a cell address (for example, B52) or a named range (for exam¬ 
ple, Interest), and the other accepts integer coordinates for cases in which using the 
coordinates in your code is more convenient, usually when you have indexes in the code 
and want to use them to index the sheet. 

■ SetRange is the same as SetCell but is used for setting values for an entire contiguous 
range. The same two versions exist as in SetCell. 

■ Refresh reads data from an external data connection (or all of a workbook’s connec¬ 
tions) and refreshes the values in the relevant cells; for example, in PivotTable cells or in 
the results of cube formulas. 

■ Calculate recalculates the formulas in a specific range or in the entire workbook. This 
method is useful when the workbook author has turned off automatic calculation. Two 
versions exist: you can use either a string or integer coordinates to refer to a range, much 
like in the Set methods. 

■ CalculateWorkbook calculates the entire workbook, using one of two calculation meth¬ 
ods: 

□ Recalculate calculates only formulas that have dependencies that changed (aka 
“dirty” formulas). 

□ CalculateFull calculates all formulas, regardless of dependency changes. 

■ GetCell gets a value from a cell. The two regular addressing mechanisms exist here as 
well. You can get either formatted string values or the raw binary values. 

■ GetRange gets a set of values from a contiguous range of cells; it has the same addressing 
flavors as GetCell. 

■ GetWorkbook gets the entire calculated workbook into your application memory as a 
byte array. You can get either the live result or a snapshot. A snapshot is essentially a 
workbook with the layout of the original workbook, with all the original formatting and 
with up-to-date values, but with the formulas and external connections stripped out and 
without the portions of the workbook that were marked during the publishing process 
not to be viewed. 
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■ CancelRequest: If your application runs the Excel Web Services session in a separate 
thread and wants to cancel a long-running server request (like a long calculation that a 
user got tired of waiting for), it can do so by calling this method. 

■ CloseWorkbook tells the server to close the workbook that it opened for this session, 
thereby also allowing the server to release all the resources it maintained for the context 
of your session. 

Error Handling 

Errors are exposed to an Excel Web Services application in three ways: 

■ Excel calculation errors show up just like they do in Excel—as cell error values 
(#VALUE!). When you call GetCell or GetRange and ask for formatted values, you’ll get 
the #-style error string. When you ask for unformatted values, you’ll get an enumerated 
error code. 

■ An error in processing one of the Web service methods (which prevents the method 
from completing successfully) is exposed as a SOAP exception that your code can catch. 

■ Less critical errors that do not prevent the method from returning normal results are 
returned as part of the method’s arguments, specifically as an output argument. The rea¬ 
son for this approach is that an exception would divert the code from its normal execu¬ 
tion path, which is not desirable with noncritical errors. Checking for these errors is 
optional. 


Sessions 

One concept that developers need to be aware of is the way Excel Calculation Services main¬ 
tains sessions for performance reasons. A good way to understand the benefit of server state 
is to think about a user who interacts with an Excel workbook in a Web browser. Each time 
the user takes an interactive step—such as revealing details in a PivotTable, changing an input 
parameter, refreshing data connections, and so on—we want the server to compute only the 
difference between what the user saw on the screen before taking that step and what they 
should see as a result of the step. For performance reasons, we do not want the server to 
read the workbook file from disk again or to recalculate formulas that do not need to be 
recalculated. 

This behavior is also desirable in situations in which an Excel server-side calculation is per¬ 
formed by the server for a custom solution that uses Excel Web Services. For example, if the 
solution’s code sets a cell to a new value, we want the server to calculate only formulas that 
depend on that cell’s value and nothing else. So, the server keeps the state, or context, of a cus¬ 
tom application’s calculation in server memory. This context is called a session. A session ID 
lets the application tell the server which session it is working with. The server returns this ID 
to the application when it starts a new session (by opening a workbook), and then the appli¬ 
cation code passes this session ID to subsequent Web service calls. 
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Controlling and Protecting Workbooks 

In this section, well review how Excel Services enables you to lock down and protect work¬ 
books. These capabilities help address an organization’s need to limit access to workbooks 
either for regulatory and audit concerns or to protect proprietary information. To further 
address this requirement, in addition to allowing users to execute and view workbooks on the 
server, the Windows SharePoint Services architecture has been extended with a new right, 
called the View Item right. 

After describing the View Item right, well show how to ensure that the workbooks users view 
are the “right” workbooks—in other words, how to control which users can author workbooks 
that will be run on the server, and which versions of those workbooks will be available for 
users to view. 

The View Item Right 

To help you understand the View Item right, think of how SharePoint is used for a document 
store on the server. Users can save and version files, administrators can control access permis¬ 
sions, and so on, all through any browser. (SharePoint does a lot more than serve as a docu¬ 
ment store, of course.) 

Currently, SharePoint administrators can give users Reader rights, which lets them look at 
content; Contributor rights, which provides permission to look at, change, and add to con¬ 
tent; or Administrator rights, which provides full control. With the View Item right, you can 
lock down workbooks that have been published to SharePoint so that users can open the 
workbooks using Excel Services, interact with them, and see the execution results, but can’t 
download a copy of the workbook or access any areas that were not published as viewable on 
the server. This right helps hide any proprietary information contained within the workbook, 
such as specific formulas, a proprietary model, external data connections, or hidden elements 
of the workbook. 



Note The View Item right is specific to SharePoint document libraries and does not work 
with workbooks that are stored in UNC shares or generic HTTP locations. 


As an example of how the View Item right can be used in an Excel Services solution, imagine 
a workbook that takes several inputs and then calculates discount rates for a large retailer. 
The discount rate for any specific distributor is dependant on many factors, including the 
quantity of product that is purchased, the time of year, and the number of previous transac¬ 
tions for a given distributor. Of course, the formula for the discount rate is carefully guarded 
by the retailer because it determines the profit made on each transaction. With Excel Services, 
this retailer can now assign a distributor View Item rights to the workbook containing this 
sensitive model without having to worry that the distributor will be able to download or see 
the model. 
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The View Item right affects how both Excel Web Access and Excel Web Services allow access 
to a workbook. The specific elements that are affected include the following: 

■ Which portions of a workbook a user can access. When a user has only the View Item 
right, he or she can see only the portions of the workbook that have been marked as 
viewable on the server during the publishing process. 

■ Which portions of the workbook can be opened in Excel. Although users with the 
Reader right can open the original workbook in Excel if they want to see the model, for¬ 
mulas, data connections, and so on, users with the View Item right can only open a 
snapshot of the original workbook in Excel. In a snapshot, a user can see the numbers 
but not the proprietary information behind those numbers (formulas, connections, and 
so on). That information, in fact, is not contained in the snapshot. (And, of course, users 
can see the numbers only for the portions of the workbook that were marked as visible 
on the server.) 

These examples focus on viewing the workbook through the browser using Excel Web 
Access. Similarly, if an application accesses the workbook through Excel Web Services, the 
View Item right is enforced. For example, issuing a call such as GetRangeAl to a range that has 
not been marked as viewable will result in an exception, as would GetWorkbook. 

Controlling Who Can Publish Workbooks to Excel Services 

The first step in controlling who can save workbooks to the server is controlling the locations 
from which the server will load workbooks. An administrator controls these locations by 
maintaining a list of directory paths as trusted locations. Excel Services checks this list before 
opening any workbook and will not load and execute a workbook unless it comes from a 
trusted location. Using SharePoint rights (for workbooks stored in SharePoint document 
libraries) or simple file system rights (for arbitrary UNC paths), an administrator can control 
who can save workbooks to these locations. Effectively, this list of trusted locations allows an 
administrator to control which users have access rights to save workbooks that will be exe¬ 
cuted by Excel Services. 

For example, on a company intranet all employees could have the rights to save workbooks 
(and other files) to various SharePoint sites within a portal. However, an administrator could 
designate one trusted location within the portal where only a select few users could save 
workbooks that would be loaded and executed by Excel Services. In turn, the users browsing 
those workbooks are guaranteed that they are viewing sanctioned copies of the workbooks. 

Controlling the Publishing Process for Workbooks in Excel Services 

When workbooks are stored in SharePoint document libraries, many more features for con¬ 
trolling the process of authoring and publishing workbooks are provided, and these features 
guarantee not only that the right version of a workbook is made available to users but that 
each workbook is subject to proper review and approval cycles. Additionally, an audit log is 
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available that tracks who accessed which workbook and when. This log is useful in the con¬ 
text of compliance processes, for example. 

The check-in, check-out, and versioning mechanisms in Windows SharePoint Services 3.0 
allow for major and minor version numbering as well as security specifically for old versions 
of workbooks (and other documents). Additionally, SharePoint has built-in functionality for 
policies around retention and expiration of documents, which means that outdated versions 
of a workbook are automatically retained and then destroyed in order to meet compliance 
requirements. 

Document approval within SharePoint allows an administrator to set up a document library 
so that when a workbook author saves a new version of a workbook to the library, the work¬ 
book is not available to other users to view immediately. Instead, the workbook needs to be 
reviewed by an administrator or an appointee, such as a financial analyst in charge of the 
library, and be approved or rejected. Only after approval does the workbook become available 
for other users who have the rights to view it. An approval process can be as simple as the 
administrator monitoring the library and changing a flag on the workbook in the document 
library, or it can be a custom workflow that sends e-mail messages to a group of approvers to 
ensure that the workbook meets any number of internal requirements prior to its approval. 


More Info For more information about workflows, see Chapter 7, "Creating Workflows: The 
Missing Piece of Office Productivity." 


Finally, Windows SharePoint Services 3.0 allows administrators to audit key events within 
document libraries. Although auditing within workbooks themselves has not been imple¬ 
mented, events such as opening, creating, modifying, and deleting workbooks are all 
recorded in a centralized log. Several built-in reports are provided to analyze that log, in addi¬ 
tion to mechanisms to generate custom Excel reports. 

Data Connection Libraries 

In the past few sections, you’ve learned about managing, sharing, and securing Excel work¬ 
books using Windows SharePoint Services and Excel Services. In this section, well cover a 
new feature that provides management, sharing, and security of data connections: the Data 
Connection Library. 

What Is a Data Connection Library? 

A Data Connection Library (DCL) is a new type of SharePoint library (much like a document 
library) that provides a location in which to store, share, and manage connection files. Con¬ 
nection files are Office Data Connection (.ode) files that contain the information and parame¬ 
ters needed to form a data connection, such as the server name, the OLAP cube or table name, 
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and a query. Because a DCL is a library in SharePoint, it provides SharePoint features such as 
workflow support, file approval, library level/item level security, and sorting and filtering 
based on metadata. You create a DCL the same way you create any library, and DCLs can be 
created on a portal or on a team site. 

The way Excel interacts with a DCL makes the DCL more valuable than just a document 
library full of connection files. In the following sections, well describe a few of the problems 
that a DCL and Office Excel 2007 help solve. 

Connecting to Databases Made Easy 

Setting up a connection to a database in Excel is a task that many users struggle with. For 
example, if they want to connect to an ODBC data source or to a SQL Server Analysis Services 
cube, users must know details such as server names, cube names, table names, what type of 
connection to create, user credentials, and so on. Lots of steps and knowledge are required. 
Office Excel 2007 and DCLs make connecting to databases a much simpler activity. Users 
need to know what data they want to work with, and that’s pretty much it. Here’s an example 
involving a PivotTable. 

To connect to a database (or to another external data source such as a Web query), a user 
clicks the Data tab. Figure 8-2 on the next pagae shows the Data tab (in the beta 1 build of 
Office 2007; this is not the final user interface). The user clicks the Existing Connections but¬ 
ton, and the Existing Connections dialog box will list the connections that are stored in a 
DCL. These connections have friendly names and nontechnical descriptions, so it is easy for 
users to choose the connection they need. The names and descriptions are provided by the 
person or persons who set up the DCL and populate it with .ode files. Users simply highlight 
the connection they want to use. At this point, they’ll see another dialog box that allows them 
to indicate what Office Excel 2007 should do with the data. Based on the connection the user 
selected, Office Excel 2007 offers only options that are possible for a particular database. For 
example, the data source in this example is a SQL Server Analysis Server database, which can¬ 
not be represented in Office Excel 2007 as a table, so that option is unavailable. At this point, 
all that is left is to click OK, and the user has connected a PivotTable to a data source. The 
whole operation is a total of three or four steps. 

But how do the connections end up in the DCL in the first place? In general, either 
connection-sawy power users or members of the IT staff will create data connection files and 
put them in the DCLs where the connections can be used throughout an organization. 

Excel knows about the existence of DCLs through a SharePoint feature that allows an admin¬ 
istrator to “advertise” the location of the DCL to Office 2007 clients, which in turn allows con¬ 
nections from a DCL to show up in Office Excel 2007. Of course, the DCL shows up only if 
the user has permissions to access the connection files the library contains. 
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Figure 8-2 The Data tab 


Solving Connection Management Problems 

In addition to improving the discoverability and ease of using connections, DCLs help users 
manage connections. For example, information about data sources, such as the server name, 
OLAP cube name, table name, and the like, can change. A typical case is a database that is 
moved from a test server to a production server. For organizations that have many users cre¬ 
ating workbooks, it can be difficult to communicate changes such as these to all the people 
who are affected. A worse situation is one in which hundreds of existing workbooks need to 
have their data connections updated. 

A DCL helps solve problems such as these because only a single connection file in the DCL 
needs to be updated with the new information. After the connection file is updated, workbook 
authors will have the correct connection information the next time they use that connection 
file, and any existing workbooks that were created using the connection file will have their 
connections updated automatically the next time that workbook’s data is refreshed. 

How exactly does this work? By default, workbooks will refresh their connection information 
from a DCL only when they fail to connect to the data source. (You might think of this as a 
failover mechanism.) But you can also force workbooks to always get the latest connection 
information before the connection is attempted. You might make use of this capability when 
you want workbook authors to start using a new database for business reports but you want 
to keep the old database up and running for auditing or test reasons. Connections to the 
old database still work, but you want current and future workbooks to start using the new 
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database. The “always use this file to refresh data” setting is a property in the .ode file itself and 
can be set when the file is created. 

Making Data Connectivity More Secure 

A DCL can also be used to make connecting to data more secure. One common security con¬ 
cern is knowing which data connections are safe to run. For example, data connections can 
contain malicious queries, or they can contain connection parameters that can slow down an 
application or compromise the integrity of the data. By creating a DCL, and by allowing only 
the most knowledgeable and trusted users to save connections to the DCL, you add a layer of 
security that helps ensure that connections coming from a DCL are safe to run. 

Much like trusted locations, Excel Services has trusted connection libraries for data connec¬ 
tions. Excel Services has a mode in which it will process data connections only from DCLs 
that an administrator has explicitly marked as “trusted” by the server. As mentioned previ¬ 
ously, data connections have many security threats associated with them; in many ways pro¬ 
cessing a data connection can be like running code. By providing trusted connection libraries, 
Excel Services gives an administrator the ability to allow only specific data connections to be 
run on the server. 

Unsupported Features in Excel Services 

Excel Services will not load every Excel file. Workbooks that contain one or more of the fol¬ 
lowing features will not load in Excel Services. 

■ Workbooks with code. This includes workbooks with Microsoft Visual Basic for Appli¬ 
cations (VBA) macros, form controls, and toolbox controls, Microsoft Excel 5.0 dialog 
sheets, and XLM macro sheets. 

■ IRM-protected workbooks 

■ ActiveX controls 

■ Embedded Smart Tags 

■ PivotTables based on “multiple consolidation” ranges 

■ External references (links to other workbooks) 

■ Workbooks saved in formula view 

■ XML expansion packs 

■ XML maps 

■ Data validation 

■ Query tables, SharePoint lists, Web queries, and text queries 

■ Workbooks that reference add-ins 

■ Workbooks that use the RTD() function 
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■ Workbooks that use workbook and sheet protection 

■ Embedded pictures or clip art 

■ Cell and sheet background pictures 

■ AutoShapes and WordArt 

■ Ink annotations 

■ Organization charts and diagrams. 

■ DDE links 



Note As noted in the preceding list, Excel Services does not support or load workbooks that 
contain VBA code. Excel Services will support user-defined functions that are written in man¬ 
aged code. Native code add-ins will not be directly supported, although native code functions 
called by wrapper functions can be used. For more information about user-defined functions, 
see "Excel Services User-Defined Functions" on page 178. 


When a user publishes a workbook to a document library, the user has the option of viewing 
it in the browser after the publish process is completed. If the workbook includes a feature or 
features that are not supported in Excel Services, the user will see a message that indicates this. 

In some cases, Excel Services will not display an object in a workbook with full fidelity as com¬ 
pared to Office Excel 2007. For example, charts displayed through Excel Services will not 
support all the visual effects included in Office Excel 2007. 

Workbooks that contain one or more of the following features will load in Excel Services but 
the features will not be displayed. (The features won’t be removed from the file, however, so 
the next time you open the file in Office Excel 2007, they will be displayed.) 

■ Split and frozen panes 

■ Eleaders and footers 

■ Page Layout view 

■ Cell patterns 

■ Zoom 

■ Analysis Services’ member properties in tooltips 

■ Some cell formatting, such as diagonal borders and border types not supported by 
HTML 

■ Interacting with files. While some features support interactivity in the browser, not all 
do. For example, users cannot add or rearrange fields in PivotTables when working with 
workbooks in a browser. 
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■ PivotCharts will not be interactive when viewed in a browser (in other words, you won’t 
be able to filter a PivotChart directly), but if you interact with the PivotTable supplying 
data for the PivotChart, the PivotChart will update accordingly. 

■ Users will be able to sort, filter, expand, and collapse data in PivotTables in a browser, 
but they will not be able to reveal all levels of detail, use SQL Server Analysis Services 
actions, add or remove fields, or rearrange (pivot) fields. 

■ In a browser, users can use either Named Object view or the provided navigation con¬ 
trols to move around a workbook, but there is no equivalent of the GoTo command. 

■ Zoom; Minimize and Maximize. These capabilities do not map well to browser-based 
viewing of workbooks. 

■ Switching to Page Layout view. A new view was designed to facilitate printing (an activ¬ 
ity that is best performed in the Office Excel 2007 client). 

■ Goal Seek and Scenario Manager 

■ Formula auditing (trace precedents, trace dependents, show formulas, and so on) 

■ Altering a workbook’s calculation mode 

■ Watch window 

As described earlier in this chapter, the full authoring of workbooks is not a scenario that was 
targeted in the initial release of Excel Services. For example, you cannot insert a chart or 
change a formula after the workbook is opened in Excel Services. The following operations 
are not supported in this release of Excel Services: 

■ Inserting a new worksheet 

■ Inserting a chart 

■ Creating a table 

■ Inserting a PivotTable 

■ Inserting a PivotChart 

■ Editing formulas 

■ Entering data into arbitrary cells 

■ Defining names 

■ Changing cell formatting 

■ Altering conditional formatting rules 

■ Grouping and ungrouping (you can interact with groups once they are defined in Office 
Excel 2007) 

■ Creating outlines (again, you can interact with outlines once they are defined in Office 
Excel 2007) 
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■ Defining consolidated ranges 

■ Converting text to columns 

Excel Services and Reporting in a Portal 

In this section, we’ll explore Excel Services some more and show how users can interact with 
workbooks that are stored in SharePoint libraries. Well also cover some of the steps required 
to configure Excel Services and Windows SharePoint Services to work together. 

Adding a Trusted Location and a Trusted Data Connection Library to 
an Excel Services Configuration 

After installing Office SharePoint Server, you need to configure trusted locations for Excel Ser¬ 
vices before you can start rendering Excel documents using Excel Web Access. This section 
outlines the steps for adding a trusted file location and a trusted data connection to an Excel 
Services configuration. 

1. Open SharePoint 3.0 Central Administration, and then click Application Management. 

2. On the Application Management page, click Create Or Configure This Farm’s Core 
Services. 

3. Click the link for the default Shared Services Provider (SSP). Figure 8-3 shows the Core 
Services page, which includes a set of links for managing Excel Services. 



Figure 8-3 The Core Services home page 
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4. Under Excel Services Management, click Manage File Trusted Locations, and then click 
Add File Trusted Location. (The list of trusted locations will be empty immediately after 
the installation.) 

5. On the Add File Trusted Location page, shown in Figure 8-4, enter the URL of your 
server (for example, http://ossl). You might also want to select the Children Trusted 
check box if you want to render documents from all document libraries on this server. 



Figure 8-4 The Add File Trusted Location page 


6. Scroll down to the External Data section of this page. Select the option under Allow 
External Data that matches how you plan to use external data with Excel documents. 
The choices are None, DCL, and DCL And Embedded. 

7. After you click OK to add this location, you should see it in the list of trusted locations, 
as shown in Figure 8-5 on the next page. You can open this page when necessary to edit 
the settings for this trusted location or add more trusted locations. 
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Figure 8-5 The trusted location list with the new item added 


Workbooks that are loaded into Excel Services might try to use connection files from a DCL 
to refresh external data. Excel Services will allow these requests to be executed only if the 
DCL is explicitly marked as trusted by the Excel Services administrator. The following steps 
detail how to set up a trusted DCL: 

1. On the home page for the site’s core services (shown earlier in Figure 8-3), under Excel 
Services Management, click Manage Trusted Connection Libraries, and then click Add 
Trusted Connection Library. 

2. On the Add Trusted Connection Library page, type the HTTP address of the data con¬ 
nection library (for example, http://ossl/DCL) that you want to add. (If this DCL is not 
available, you will have to create the library first.) Optionally, add a description. Figure 
8-6 shows the completed page. After you complete this step, Excel Services is able to 
load .ode data connection files from the DCL that you configured. 
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Figure 8-6 Adding a trusted data connection library 


Building a Report for Excel Web Access 

The scenario in this section shows the processes of building a report based on data stored in 
a SQL Server Analysis Services Unified Dimensional Model (UDM) using Office Excel 2007 
cube functions, and then publishing the report to Office SharePoint Server for viewing within 
Excel Web Access. 

To start, we need to create the data connection to be used in the report. The first step is to 
open a new workbook in Office Excel 2007 and then add external data to the workbook. You 
do this by clicking Data, Create New Connection, New Analysis Services Connection, as 
shown in Figure 8-7 on the next page. 

To create the connection, you step through screens in the Data Connection Wizard. You enter 
the name of the Analysis Services server that contains the cube you want to use, and select the 
database and the cube. This example uses Adventure Works DW as the database and the 
Adventure Works cube. After you click Finish in the wizard, Excel prompts you for details 
about how you want to import the data. For this example, we need to select Only Create Con¬ 
nection, as shown in Figure 8-8 on the next page. You can use the Properties button to name 
the connection and to set other properties. For example, on the Definition tab of the Proper¬ 
ties dialog box, you can click the Export Connection File button to save the connection file to 
a data connection library or to another location. 
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Figure 8-7 Creating a new connection to external data in Office Excel 2007 
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Figure 8-8 Use this dialog box to choose an option for importing external data. 

To place the data connection file in a SharePoint data connection library, you can also open 
the library and upload the file. After checking in the file to the DCL, you need to approve the 
check-in to make the connection available to users. In the Data Connection Library list view, 
open the drop-down menu for the data connection, and then click Approve/Reject. Figure 8-9 
shows the DCL we created earlier with the Adventure Works data connection file checked in 
and approved. 

Next we’ll create a workbook that uses the Adventure Works data connection. In Excel, click 
Data, Existing Connections, Open Connection. In the Existing Connections dialog box, 
choose the Adventure Works connection. When prompted for the import option, select Only 
Create Connection. 
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Figure 8-9 The approved data connection file in the trusted data connection library in SharePoint 


The next step is to start filling out the body of the report, including a title and header rows. 
Then we’ll add the rows of the table and actual references to the external data. Figure 8-10 
shows the data added to Sheet 1 (renamed Reports), including the cells that well use later as 
parameters for the report (defined in D4 and D5) and their initial values (E4 and E5). Setting 
up these parameters gives users the ability to change the values in the report to reflect a spe¬ 
cific year and location. When we publish this workbook to the server, well declare these cells 
as parameters. 
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Figure 8-10 The report title, column headings, and parameters set up for the report 

Figure 8-11 on the next page shows how the external data connection is used in conjunction 
with a new Office Excel 2007 feature called cube formulas to return data from our data 
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source. We entered these formulas on Sheet! of the workbook. Column A includes descrip¬ 
tive labels of the data the formulas retrieve. 
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Figure 8-11 Cube formulas used in Excel to retrieve external data from an Analysis Services cube 

When you enter cube formulas, Excel provides a list of OLAP-based connections that have 
been defined in the workbook. When a cube formula expects a set_expression argument, as 
you begin to enter the argument Excel fetches available dimensions, hierarchies, measures, 
and member names directly from the cube so that you don’t need to enter the entire member 
name by hand. 

One final item to note here is that you can provide Excel with any valid multidimensional 
expression (MDX) fragment that resolves to a member or to a set for member_expression and 
set_expression arguments. For example, in cell BIO, the set expression [Product],[Subcate¬ 
gory].[All Products], children is a valid MDX expression that returns all the product subcatego¬ 
ries. 

The previous step got the data needed to fill in the body of the report, which now contains the 
top 10 product subcategories sorted by reseller sales based on the year and geographical loca¬ 
tion specified by the user. The final formula, found in cell BIO, provides the sorted set that will 
be used to construct each individual row of the report. In the next step, we return to the 
Reports worksheet and enter the cube formulas that are used to create each row in the report. 
Here are the cube formulas used for the report’s columns: 


■ B8, SubCategory 
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=CUBERANKEDMEMBER("Adventure Works",Sheet2!$B$ 10,ROW(Bl)) 

■ C8, Reseller Sales 

=CUBEVALUE("Adventure Works",$B8,Sheet2!$B$9) 

■ D8, Reseller Gross Profit 

=CUBEVALUE("Adventure Works",$B8,Sheet2!$B$3,Sheet2!$B$4,"[Measures]. [Reseller 
Gross Profit]") 

■ E8, Reseller Freight Cost 

=CUBEVALUE("Adventure Works",$B8,Sheet2!$B$3,Sheet2!$B$4,"[Measures]. [Reseller 
Freight Cost]") 

In cell B8, the formula returns the first item from the CUBESET function on Sheet2!B10 by 
using the formula ROW(Bl), which evaluates to 1. The ROW function is a great helper func¬ 
tion when you’re building sheet data reports and you need to retrieve individual items from a 
set. 


To provide the rest of the report’s data, you can simply fill down the formulas in the rows. The 
report body now appears as in Figure 8-12. 



uu 10 Roller Reptnleln ' ' 

j-.'.-n f-.,' 



. S 



A =0 ■ O U.rrt 

Insert P.igr layout FonMildt Data flrwew 

_ 


-H- 





T | i A 44 

r otun • D • ^ ^ 



* Ctllbn ▼ 

u w A* a" ■= * =* ^ Sf J- 

u«ntrti ■» 









, n / o A 

* z • ■ « ■«-- a 

5 % * :a a 

Cell Formal Ai 
Slytri - Tabi/ 

Conditional . Sort & Find & 

Format - ^ - Fm „ vtrrt 








H19 

/. 




S 


A 0 

C 0 

c 

F G 

L M 1 1 J K 


l 



2 

Top 10 Product Subcategory Reseller Report 


3 

4 


Date 

7007 




•j 


Geography 

United States 




0 



7 

Subcategory 

ResellerSales Reseller Gross Profit 

Reseller Freight Cost 




ft 

Road fiii". 

7746385.417 778938.7798 

193659.697 




9 

Mount.lin Riki". 

6970418.73ft 46154.3679 

174760.4931 




10 

Road Frames 

11U0//9.195 73287.244H 

2/519.4918 




11 

Mountain Frames 

1019904.647 121233.279 

25499.6147 




12 

Wheels 

311123.2783 80825.806 

7770.0957 




1 ft 

rights 

79800.084 73675.0796 

1995.0097 




14 

Jerseys 

74165.3323 -3554.1603 

1854.1298 




IS 

Bib-shorts 

640/7.0646 19680.4682 

1601.933/ 




16 

Gloves 

59284.0285 15486.0414 

1482.1054 




17 

Helmet* 

49586.497 15304.5454 

1739.669? 




IK 



19 

1_1 


20 







21 







77 







a 



24 



25 







76 






• 


► n Report* Sheet! 

SheeU • J 


• 

* 


Ready <j 




view * .3 3 a icwk. w y w 


Figure 8-12 The report with data drawn from the external data source 


Our goal for this report is to produce a pie chart, and we want the chart to contain a slice that 
represents the subcategories that didn’t make the top 10 list. To accomplish this, we can enter 
the label All Others in cell B18 and the following cube formula in cell C18: 
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Sheet2!B5) - SUM(C8:C17) 


Note You could apply other formatting features to a worksheet such as this. For example, 
you could format it as a table (using the Insert ribbon) and apply a table style. You could make 
the number formatting consistent. Finally, you could finish formatting the table by using Office 
Excel 2007's data bar functionality, which adds a colored background to a cell in proportion to 
a cell's relative value in a column. 


To create a pie chart based on the data in the SubCategory and Reseller Sales columns, we first 
select these columns and then use the Insert ribbon to insert a chart. After clicking OK, the 
chart is added to the workbook, as you can see in Figure 8-13. With the chart in place, you can 
add a chart title or do other chart formatting as you like. 



Figure 8-13 The report data represented in a pie chart 

The report is complete from a presentation perspective. Now we need to publish this work¬ 
book to Office Server so that it can be shared with the rest of the organization. In this scenario, 
we will share the chart and the Reports sheet but not the entire workbook. As mentioned ear¬ 
lier, we could make the entire workbook available to users, but we’ll use the Named Object 
view here to enable portions of a worksheet to be published. In addition, we’ll let users change 
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the report’s data by entering a different country and year through workbook parameters. To 
add the parameters, we create a couple of named ranges in Excel that represent the cells in 
which the year and country values are entered, E4 and E5 in the Reports worksheet. (You can 
name cells by entering the name in the Name box, just to the left of the formula bar.) 

To start the process of publishing the workbook to Office Server, we choose File, Send, Pub¬ 
lish To Office Server. In the Excel Services Options dialog box, we set up the parameters by 
clicking the Parameters tab, shown in Figure 8-14, and then adding the two named cells as 
parameters for the workbook. This list of parameters is based on those cells in the workbook 
that are defined as named ranges. Named ranges that are defined as a single cell and that only 
contain values are eligible for being workbook parameters. 



Figure 8-14 Defining parameters that users can interact with when viewing the workbook's data in 
the browser 


On the Show tab, a drop-down list provides three publishing options: Entire Workbook, 
Sheets, and Items In The Workbook (such as the chart or table in the example we’ve been 
showing). We selected the chart and the Reports sheet to be viewable on the server. 

Note Remember that regardless of which option you select here for the items that can be 
viewed on the server, a copy of the entire workbook is saved to the location where you publish 
the workbook so that cell references and data models are available. For example, in this case 
the chart relies on data that is in the table (not marked for display) and the table relies on data 
from Sheet2 (also not marked for display). 


Figure 8-15 on the next page shows what the workbook looks like in Excel Web Access, after 
making the chart and the Reports worksheet available and publishing the workbook. When a 
user changes the values of the parameters, the chart and table will update to reflect the change 
in the parameter values. The complete set of data is available because the entire workbook is 
loaded on the server, but the user has the ability to see only the elements you published. 
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Figure 8-15 The chart opened in Excel Web Access. 

Coding with Excel Web Services 

In this section, well describe two examples that use managed code to incorporate logic in an 
Excel workbook into an application. The integration is achieved by calling Excel Web Services 
to run the Excel portion of the logic on the server. The first example involves a Monte Carlo 
simulation model for a stock and option portfolio. The user of this application runs a com¬ 
mand line tool and entered some arguments for the command. The code passes the argu¬ 
ments to the server through Web service method calls and receives back results. The results 
are then sent to the console. The second example shows similar code used in part of a simple 
Web-based mortgage calculator that could be run from a SharePoint Web Part. 

Monte Carlo Simulation 

We used a console application in this example because it enables us to show a complete 
application while focusing on the Excel Web Services aspects rather than on user interface 
considerations. Typically, code that uses this Web service would be a server-side, middle-tier 
application such as an .aspx page or a Web application. 

Figure 8-16 shows two worksheets from the Monte Carlo workbook that we will make avail¬ 
able to Excel Services and access through Excel Web Services. The worksheet named Simula¬ 
tion holds the proprietary calculation model that we want to protect on the server and use in 
an application. For this sample, the model is just a few randomly generated numbers, but the 
workbook interface to the application is demonstrated just as if this were an elaborate and 
truly valuable calculation model. 
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Figure 8-16 The Monte Carlo workbook. We want to use the logic on the Simulation sheet in an 
application. 

To publish the workbook to Office SharePoint Server, we follow the steps described in the 
previous section, making sure that we don’t publish the Simulation sheet. We can then write 
some code to interact with the Excel workbook using the Web service. 

In Microsoft Visual Studio, we create a C# console application project and name it Monte- 
Carlo. We first need to add a Web reference to Excel Web Services, which is http://ossl:500/ 
_vti_bin/excelservice.asmx, and add a using statement for the new namespace: 

using MonteCarlo.myserver; 

Next we define the interface between our application and the Excel workbook. The interface 
is a set of named ranges that are associated with input and output cells. 

class Program 
{ 

// input & output cell names 

private static string [] inputcells = {"Symbol", "ini ti al Pri ce" , 

"Strikeprice", "interest" 

private static string[] outputcells = {"Average", "VaR", 

"RelDeltaNormal; 
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Note Both direct range references (for example, B52) and named ranges can be used. Using 
named ranges isolates the parameter location in the workbook from the application, making 
the model easier to maintain. 


Then we add code to display a usage line when the command is run with an insufficient num¬ 
ber of arguments: 

static void Main(string[] args) 

{ 

if (args.Length < 1 + inputceiis.Length) 

{ 

Console.Error.write("usage: MonteCarlo <workbookPath>"); 
foreach (string argName in inputCells) 

Console.Error.write(" <{0}>", argName); 

Console.Error.writeLine(""); 
return; 

} 

The usage line will help at run time because it refers to all the required arguments: a path to 
the server-side Excel workbook and the input cell names that you defined in the previous 
step. 

Next we add code to instantiate and initialize the proxy object: 

// Excel web services stuff: 

// instantiate and initialize the service proxy object 
ExcelService xlsrv = new ExcelServiceO; 

xlSrv.Credentials = System.Net.CredentialCache.DefaultCredentials; 


Setting credentials to DefaultCredentials means that your process security context is passed to 
the Web service for authentication. 

The next step is to open the workbook and start a session with Excel Services. 

// Open the workbook 
Status[] status; 

string sessionld = xlSrv.Openworkbook(args[0], string.Empty, string.Empty, out status 

The OpenWorkbook method returns a sessionld, which is used in subsequent calls as a user’s 
session context. The two empty strings designate default cultures (languages) to be used. The 
status output argument returns an array of noncritical errors (usually empty). Critical errors 
are returned as SOAP exceptions that you can catch. 

We next set the values that are passed on the command line to cells in the workbook, using 
the array of input named ranges that were defined earlier. After setting these values, we call a 
method to have the server calculate the new state of the workbook. 

// Set parameter values into cells 

for (int i =0; i < inputCells.Length; i++) 
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status = xlSrv.SetCellAl(sessionld, "Sheetl", inputcells[i] , args[l+i]); 

// Calculate the workbook. 

■ status = x1Srv.Calculateworkbook(sessionld, CalculateTypc.Recalculate) ; - 

Note When a model is complex and time consuming to calculate, it is often a good idea to 
turn off automatic recalculation when authoring the workbook in Excel. When automatic 
recalculation is turned off, the server will not perform recalculations after each parameter 

_Yalu£4^QUJ£t^and4tQJLLn££dLto£xpMllviinslm.clJb£L££^^ 

after all parameters are set. 


After the workbook is calculated, you can get output values from the server session, using the 
array of output named ranges that you just defined, and write them out. 

// Get results and write them out. 
foreach (string cell Name in outputcells) 

{ 

object result = xlSrv.GetCellAl(sessionld, "Sheetl", cellName, true, out 
status); 

Console.writeLine("{0}:\t{l}", cellName, result); 

} 

As a last step, we close the workbook and your server session. This step is important for opti¬ 
mization. If you do not close the session when you are finished with it, the server will still time 
out the session after an amount of time (controlled by an administrator) passes. This time-out 
period is usually set according to the needs of graphical applications to allow users to pause 
between interactions. Unnecessary sessions that remain open consume server resources and 
can cause decreased overall performance. 

// Close the session. 

status = xlSrv.Closeworkbook(sessionld); 

After building the application in Visual Studio, we can run it without arguments to get the 
usage line. 

...\Debug>MonteCarlo.exe 

Usage: MonteCarlo <workbookPath> <Symbol> <lnitialprice> <Strikeprice> <InterestRate> 

Now we pass it the path to the Excel workbook and values to the other arguments. Here are 
the result values that are written out. 

...\Debug>MonteCarlo.exe "http://ossl:500/report/reportlibrary/MonteCarlo.xlsx” MSFT 26 
Average: $80,950.37 
VaR: $1,165.32 
RelDeltaNormal: -53.026% 
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A Simple Mortgage Calculator 

The mortgage calculator example, much like something you would find on a bank’s Web site, 
is similar to the Monte Carlo scenario. Although it’s another simple application, it demon¬ 
strates key Excel Services concepts such as the following: 

■ Using a server-side Excel workbook calculation as part of another application. 

■ Writing a custom, interactive user interface around Excel Calculation Services. (The 
user interface for this application could be a SharePoint Web Part or any other format 
that can communicate with Web services.) 

■ Protecting and maintaining proprietary business models while still providing users with 
the ability to enter their own inputs and receive answers. There’s no need to recode an 
Excel model just to protect it. 

The example here is a simplified version of such a tool, with one twist: the entire calculation 
is performed on the server by an Excel workbook and not by a function written in a program¬ 
ming language. As far as the users are concerned, the tool does not appear to be related to 
Excel; it is just an ordinary interactive Web form. A user can type in the mortgage amount, 
mortgage period length, and interest rate; click Calculate; and see their prospective monthly 
payment on the form. Behind the scenes, the Web page uses an Excel Web Services session to 
load the mortgage calculator workbook, set its parameter cells to the values provided by the 
user, and retrieve the calculated result from the appropriate formula cell. 

The entire calculation is performed in a single cell by using the Excel PMT function. We name 
this cell Payment. Similarly, we can define three input parameter cells that are also named, 
although they don’t have to be named to be exposed by Excel Web Services. Cell references 
can be used as well. However, using named cells better isolates the workbook and the code 
around it; the code refers to the sheet only through named ranges so that the model can be 
edited later and laid out in any way that the author sees fit, as long as the parameter and result 
names remain intact. The workbook is published to a server document library. 

The following sample code, which relates to running Excel Web Services sessions, is con¬ 
tained within a single method that is called from a button control’s Click event. This applica¬ 
tion would use standard Web Part code for the user interface and other operations. 

private void Calculateusingwebservice() 

{ 

Status[] status; 
string sessionld = null; 

// Step 1: instantiate the web service 
xlMortgageCalcwebPart.Es.ExcelService es = new 
xlMortgageCalcwebPart.Es.ExcelService(); 

// Step 2: Set web service link 
es.url = this.ExcelwebServiceurl; 
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// Step 3: Set credentials 

es.Credentials = System.Net.Credential Cache.DefaultCredentials; 

// Step 4: Start the session 
try 
{ 

sessionld = es.Openworkbook(this.MortgageCalculatorworkbookurl, 

String.Empty, String.Empty, out status); 

} 

catch 

{ 

sessionld = null; 

} 

if (sessionld == null) 

{ 

_lblError.Text = "Error opening workbook. Please make sure that the 
correct MortgageCalculatorworkbookurl and ExcelwebServiceurl are 
specified in the web Part Properties."; 
this.Controls.Cl ear(); 
this.Controls.Add(_lblError); 
return; 

} 

// Step 5: Set parameters 

es.SetCellAl(sessionld, "SimpleCalculator", "MortgageAmount", 

_txtMo rtgageAmount .Text.TrimO); 
es.SetCellAl(sessionld, "SimpleCalculator", "MortgageLength", 
_txtMortgageLength.Text.Trim()); 
es.SetCellAl(sessionld, "SimpleCalculator", "interestRate", 
_txtlnterestRate.Text.TrimO); 

// Step 6: Get result 

object o = es.GetCellAl(sessionld, "SimpleCalculator", "Payment", true, 
out status); 
if (o != null) 

{ 

_1blTotal.Text = Convert.ToString(o); 

} 

el se 

{ 

_1blError.Text = "Error getting total value from workbook."; 
this.Controls.Clear() ; 
this.Controls.Add(_lblError); 
return; 

} 

// Step 7: End the session 

status = es.Closeworkbook(sessionld); 
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To instantiate the Web service, the code creates an instance of the ExcelService object, which is 
generated by Visual Studio when a developer adds a Web reference to the Web service’s .asmx 
file. As you can see, the object is generated in the application’s namespace. 
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The code sets the URL to the Web service and then sets credentials. In this case as well, we set 
the credentials that are passed to the Web service for authentication to DefaultCredentials , 
meaning that the application’s own credentials are used. 

To start the session, the code calls OpenWorkbook, passing the path to the mortgage calculator 
Excel workbook (a Web Part property in this case) and receiving a sessionld. This sessionld is 
used later in other Web service calls to identify our session. 

The code next calls SetCellAl to set the three parameter cells to the values that a user of the 
application has entered in the Web Part form. You can see how named ranges are used, as 
opposed to direct cell references, to make the code insensitive to layout changes in the work¬ 
book and thus more robust. 

The call to GetCellAl retrieves the calculation’s result, the value in the Payment named range. 
The sample workbook was set to be automatically recalculated, so as soon as the parameters 
are set, users can expect the result to be available. In some cases, automatic recalculation is 
turned off while authoring the Excel workbook; a call to Calculate is then necessary at the 
point in the code at which you want to tell Excel Calculation Services to explicitly calculate 
formulas. 

To end the session, the code calls CloseWorkbook. This call tells Excel Calculation Services that 
we are finished with this session and that all resources that were associated with the session 
can be released. 

That’s it. In seven lines of code and some exception handling, we have integrated an Excel 
workbook calculation on the server with our mortgage calculator application. The application 
provides a custom user interface, Excel Services processes the Excel workbook model, and 
Excel Web Services ties this functionality together. 

While this is a simple example, you can envision more complex calculations represented in 
workbooks that you can call from an application. The calculations can be provided as a ser¬ 
vice to applications, while the calculation model is safely hidden and secured. 

Excel Services User-Defined Functions 

We’ll conclude this chapter with some information about user-defined functions (UDFs), 
which are a mechanism by which developers can extend Excel Calculation Services. 

To create a UDF, you must use Visual Studio 2005 because your project needs a reference to 
the Excel Services UDF dynamic link library, Microsoft.Office.Excel.Server.Udf.dll. This assem¬ 
bly has been compiled using .NET Framework 2.0. It is located on the computer where you 
have installed Office SharePoint Server in the following path: 

[drive:]\Program Files\Common Files\Microsoft Shared\web server extensions\12\ISAPI 
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Note If you use Visual Studio 2003 to create a managed-code UDF, you will not be able to 
reference Microsoft.Office.Excel.Server.Udf.dll. It is not possible for an assembly created using 
an older version of the .NET Framework to reference an assembly created using .NET Frame¬ 
work 2.0. 


UDF assemblies can reside either in a local directory or in the Global Assembly Cache (GAC). 
In a farm scenario, the local directory path must be identical across the farm. A UDF assembly 
also has to be present on a local disk on the same computer that runs Excel Calculation 
Services. 

By default, UDF assemblies are disabled. The Excel Services administrative pages in Windows 
SharePoint Services Central Administration maintain a User-Defined Functions list for each 
Shared Services Provider (SSP). Each trusted location has an AllowUdfs flag as well. The 
default AllowUdfs value is False, which means the UDF assemblies in that particular trusted 
location are disabled. If the AllowUdfs value is False when a session is started in a workbook 
that has UDF calls, the UDF calls will fail. A change in this flag takes effect on the next session. 
Administrators have to register all UDF assemblies and enable them by setting the AllowUdfs 
flag to True. 

By default, UDF assemblies run with full trust. If you don’t want a particular UDF assembly to 
run with full trust, you must explicitly restrict code access security (CAS) permission for that 
UDF assembly. You can do this by using the CAS Exclusive attribute. Developers can also use 
the RequestMinimum and RequestOptional methods in their code to manage permissions. 

A UDF class in a UDF assembly can be public or sealed. It cannot be abstract, internal, or pri¬ 
vate. It must have a parameterless, public constructor. When you create a UDF assembly, you 
need to mark your UDF class using the Microsoft.Office.Excel.Server.Udf.UdfClass attribute. 

You must mark UDF methods using the Microsoft.Office.Excel.Seryer.Udf.UdfMethod attribute. 
Methods that are not marked with the Microsoft.Office.Excel.Server.Udf.UdfMethod attribute 
in the UDF assembly are ignored because they are not considered UDF methods. The 
Microsoft.Office.Excel.Server.Udf.UdfMethod attribute has an IsVolatile property. You use this 
property to specify whether a UDF method is volatile or not. The default value of IsVolatile is 
False, which means that particular UDF method is nonvolatile. 

A UDF method in a UDF assembly must be public and it must be thread-safe. A UDF method 
cannot have ref or out parameters, use the retval attribute, use optional arguments, or use 
unsupported data types. The UDF method supports numeric types (Double, Single, Int32, 
UInt32, Intl6, UIntl6, Int64, UInt64, Byte, Sbyte), strings, Boolean, object arrays (one- or 
two- dimensional arrays, that is, object [] and object [,]), and DateTime data types. Supported 
return value types are as follows: 


■ Numeric types: Double, Single, Int32, UInt32, Intl6, UIntl6, Int64, UInt64, Byte, Sbyte 
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■ String 

■ Boolean 

■ Object arrays: The arrays can be one or two dimensions 

■ DateTime 

■ Object 

■ Object (Null) 

Here’s an example that shows work with a UDF project in Visual Studio 2005. The project is 
a C# Class Library project named SampleUdf. Before writing the class, we need to add a refer¬ 
ence to Microsojt.Office.Excd.Server.Udj.dll. To get to this assembly, we click the Browse but¬ 
ton in the Add Reference dialog box, and then go to 

[drive:]\Program Files\Common Files\Microsojt Shared\web server extensions\12\ISAPI 

If you are working on a computer that does not have Office SharePoint Server 2007 installed, 
you need to copy this assembly from a computer that includes Office SharePoint Server 2007. 

After we add a reference to Microsoft.Office.Excel.Server.Udf.dll, the next step is to create some 
custom functions and mark them with the user-defined function attributes. As mentioned ear¬ 
lier, you must mark a UDF class with the M icrosoft.Office.Excel.Server.Udf.UdfClass attribute 
and UDF methods with the Microsoft.Office.Excel.ServerUdf.UdfMethod attribute. Here’s the 
completed code for the class showing the attributes. 

using System; 

using System.Cot lections.Generic; 
using System.Text; 

using Microsoft.Office.Excel.Server.udf; 

namespace SampleUdf 
{ 

[udfclass] 

public class Classl 
{ 

[UdfMethod] 

public double MyDouble(double d) 

{ 

return d * 9; 

} 

[UdfMethod(lsvolatile = true)] 
public DateTime ReturnDateTimeTodayO 
{ 

return (DateTime.Today); 

} 

} 

} 
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The first UDF function takes a number (of type double ) and multiplies the number by 9. The 
function is a UDF method that is not volatile. (Because the default value for the IsVolatile prop¬ 
erty is False—which means that particular UDF method is not volatile—it is sufficient to mark 
a nonvolatile UDF method as [UdfMethod], You don’t need to mark it as [UdfMethod(IsVolatile 
=false)].) The second function returns the current date using the System.DateTime. Today prop¬ 
erty. This function is marked volatile. 

Remember that you need to deploy a UDF assembly to a location that has been designated a 
trusted location in Excel Services and also enable the UDF. You enable UDFs for a location 
using links for Excel Services Management on the Core Services home page, which you’ve 
seen earlier in Figure 8-3. 

Two links are used to enable UDFs: Manage Trusted File Location and User-Defined Func¬ 
tions. You use the first link to edit the properties of a trusted location, enabling an option to 
allow user-defined functions. You use the User-Defined Functions link to specify a name of a 
particular UDF assembly that you want to trust. 
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Microsoft Office Forms Server 2007, like Excel Services, builds on Microsoft Windows Share- 
Point Services 3.0 and Microsoft Office SharePoint Portal Server 2007. Office Forms Server 
2007 can be used to render editable Microsoft Office InfoPath 2007 form templates in a 
browser in HTML, making the forms available to users who don’t have Office InfoPath 2007 
installed on their client computers. 

In this chapter, we’ll provide an overview of Office Forms Server 2007, including a description 
of classes that can be used to automate administrative tasks. We’ll describe some of the situa¬ 
tions in which Office Forms Server 2007 supports the use of InfoPath forms, its architecture, 
and some aspects of designing form templates that will be enabled for viewing in a browser. 
We will also illustrate some of the steps involved in deploying a form template to Office 
Forms Server 2007 and how you can use an InfoPath form on a Web page or in a Windows 
application. 
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Key Scenarios 

The introduction of Office Forms Server 2007 greatly increases the number of scenarios in 
which InfoPath form templates can be deployed. (Each scenario, of course, would entail spe¬ 
cific considerations for deployment topologies, scaling requirements, workflows, and other 
information.) Some of these scenarios include the following: 

■ An international importing company could use Office Forms Server 2007 to query sup¬ 
pliers about inventory. 

■ Local government agencies could use Office Forms Server 2007 to manage processes 
over the Internet, such as contractor permit applications and approvals. 

■ A department within a large organization could deploy Office Forms Server 2007 to col¬ 
lect information from planning meetings with customers, using forms that are con¬ 
nected to a database. This configuration would enable employees to retrieve and analyze 
the data they collect from many different meetings at a later time. 

■ An organization such as an insurance company could use Office Forms Server 2007 to 
communicate with agents in addition to policyholders and business partners. All of the 
processing for documents such as insurance claims could be managed online. 

The main aim of Office Forms Server 2007 is to enable users who do not have Office InfoPath 
2007 installed to view and fill out forms while working in a Web browser. Form templates 
(.xsn files) designed in Office InfoPath 2007 are translated into browser-editable forms that 
run on Office Forms Server 2007. Form templates with custom business logic are deployed by 
an administrator to the Windows SharePoint Services content database and are safe-listed in 
the configuration database. Form templates are managed through a global list of form tem¬ 
plates on the SharePoint Central Administration form template management page, which is 
shown in Figure 9-1. 

The same form template can be designed to be deployed to Office Forms Server 2007 (making 
it available through a Web browser when Office InfoPath 2007 is not available) and to run in 
Office InfoPath 2007. A form that is designed for both Web browsing and for Office InfoPath 
2007 is generally restricted to using only features that are common to Office InfoPath 2007 
and the Office Forms Server 2007 browser-based run times. For example, business logic built 
into form templates that are compatible with Office InfoPath 2007 and Office Forms Server 
2007 can be developed only in C# or Microsoft Visual Basic .NET. These development lan¬ 
guages can only call members of the new InfoPath managed-code object model provided by 
the Microsoft. Office.InfoPath assembly. 
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Figure 9-1 Form templates are managed in SharePoint Central Administration. 


Components and Architecture 
of Office Forms Server 2007 

The rendering component of Office Forms Server 2007 is the FormServer.aspx page, which 
resides in the _layouts folder of the server. This page can accept multiple parameters, includ¬ 
ing the following: 

■ XMLLocation populates the Web-based form template with data that overrides the 
default form template data. 

■ XSNLocation is a pointer to the form template solution file (.xsn). 

■ Openln specifies whether the form should be opened in Office InfoPath 2007 or in the 
browser. 

■ SaveLocation overrides XMLLocation as the default location where a submitted form is 
saved. This parameter is optional. 

■ SourceLocation is the location to which the browser navigates after a form is submitted. 

■ DisableSave is a property used to hide the Save button in a Web-based form. 
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For URLs with an XML file or an XSN, logic in FormServer.aspx sends the form template to 
InfoPath if it is present on the client computer; otherwise, it renders the template in the 
browser. FormServer.aspx uses a special header value in the page and a registered MIME type 
to launch Office InfoPath 2007. An option on the Advanced Settings page for a form library 
(named Opening Documents) specifies whether to open a form in the InfoPath client if the cli¬ 
ent is available. 

Client Architecture and Postback Optimization 

When a Web-based form template is rendered, an XML payload and HTML are sent to the 
browser along with supporting]Script files, which are cached in the temporary browser cache. 
Subsequent postbacks from the browser optimize the changes in the XML payload sent from 
the server, and local scripts handle the HTML update of the page. On custom pages, if a full 
reload of the page occurs, operations are similar to loading a page for the first time in that the 
full XML payload and the HTML are sent to the browser. 

The Form Template Converter 

When a form is converted, the XSN file (which corresponds to a form template) is converted 
to the files needed by Office Forms Server 2007 to run the same form in the browser. Form 
conversion will log an entry if certain XSL constructs are encountered, such as apply-templates 
with no matching template, apply-templates with multiple matching templates, xsl.imports, and 
others. 

Form conversion will stop if the operation encounters either unsupported controls or unsup¬ 
ported Office InfoPath 2007 features for which Office Forms Server 2007 cannot provide an 
appropriate behavior. 

Data Connections and Office Forms Server 2007 

Some differences exist with respect to how data connections behave for a form template 
opened in Office InfoPath 2007 and a Web-enabled form template that is opened from Office 
Forms Server 2007. In general, Web-enabled form templates should use Web services for 
retrieving and submitting data. If using a Web service is not possible, developers must 
address some limitations about data connections when designing a template for the server. 
For example, the Human Workflow Services adapter set is not supported on the server. In 
addition, the database adapter becomes read-only (submit is disabled). When using a Web 
service with DataSet objects, changes in the data are not tracked. 

The following types of data connections are available through Office Forms Server 2007: 

■ Database 

■ E-mail 
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■ HTTP post 

■ SharePoint (the native API is used for same-domain data connections; Distributed 
Authoring and Versioning [DAV] extensions are used for cross-domain connections) 

■ SharePoint list 

■ Web services 

■ XML file 


Designing Form Templates 

The following sections outline which form template controls are supported in Web-enabled 
form templates, levels of support for different browsers, and considerations for designing 
form templates in Office InfoPath 2007. 


Controls Supported on Office Forms Server 2007 

The following standard controls are supported on Office Forms Server 2007: 


■ Text box 

■ Rich-text box 

■ Drop-down list box 

■ List box 

■ Date picker 

■ Check box 

■ Option button 

■ Button 

Office Forms Server 2007 also supports the following container controls: 


■ Repeating section 

■ Repeating table 

■ Section 

■ Optional 

In addition, hyperlink and expression box controls (two of the advanced controls) are 
supported. 
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Controls Not Supported on Office Forms Server 2007 

The following controls are not supported on Office Forms Server 2007: 

■ Combo box 

■ Multiple-selection list box 

■ Master/Detail 

■ Bulleted, numbered, and plain list 

■ Picture 

■ Ink picture 

■ File attachment 

■ Vertical label 

■ Scrolling and horizontal region 

■ Fiorizontal repeating table 

■ Choice group 

■ Repeating choice group 

■ Choice section 

■ Repeating recursive section 

■ Custom controls 


Browser Support 

Office Forms Server 2007 supports a number of different browsers on various operating sys¬ 
tems. The extent of the support is based on four levels. 

■ Level 1 offers full fidelity and provides the best experience with a Web-enabled form. 

■ Level 2 provides a fully functional experience, but certain features (such as a date picker 
control) might not be available on some of the browsers. 

■ Level 3 does not provide full fidelity. Certain features might not work and rendering will 
differ significantly between browsers. 

■ Level 4 offers no support and possible blocking. 

The following table lists browsers, operating systems, and corresponding levels of support. 



Note The information in the following table is subject to change. 
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Browser Support Matrix 

Operating System 

Browser 

Level 1 

Windows SharePoint Services 
Forms Administration 

Windows 98, Windows Me, 
Windows 2000, Windows XP, 
Windows Server 2003 

Internet Explorer 6.x (plus the 
64-bit version) 

Level 2 

Internet, Windows SharePoint 
Services Site Administration, 

Windows 98, Windows Me, 
Windows 2000, Windows XP, 
Windows Server 2003 

Internet Explorer, Firefox, 
Netscape 7.2 (moving to 8.x) 

Form Filling for a majority 

UNIX/Linux 


of users 

Mac OS X 

Firefox, Safari 1.2 

Level 3 

UNIX, Linux, Windows 


Limited support 

(versions other than above) 


Level 4 

No support 

Everything else 

Everything else 


Controlling Postback Behavior When Control Values Change 

The properties dialog boxes for controls in Web-enabled form templates provide settings to 
manage when and whether the browser will post back data and refresh the page when the 
control’s value changes. These postback settings can be found on the Browser Forms tab of a 
control’s properties dialog box. 

Deployment 

A codeless form template can be deployed to Office Forms Server 2007 by using the Office 
InfoPath 2007 user interface. A form template containing code that encapsulates custom busi¬ 
ness logic must be activated on the forms server by an administrator and requires Administra¬ 
tor privileges. 

Custom business logic assemblies should be strong-named to support side-by-side versioning 
of form templates when business logic changes. If you upgrade a form template with changes 
to its business logic, the identity of the assembly should also be changed because the assem¬ 
blies run in the same Windows SharePoint Services application domain and cannot be 
dynamically unloaded. 

If a form template needs to be accessible from inside a firewall and externally (as in an extra- 
net scenario), Office Forms Server 2007 works with Windows SharePoint Services 3.0 Alter¬ 
nate Access Mapping (AAM). AAM works for all connections in the form template, in addition 
to multiple URLs to the same form template, but it will not resolve linked image controls, 
hyperlinks in user data, and database and e-mail data connections. 

Deploying a form template to Office Forms Server 2007 is preceded by a verification step that 
involves passing the form through the converter to ensure that the form is server compliant. 
A verification page will return a list of any errors and warnings for the form template. 
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Deployment can be accomplished either directly or as a combination of uploading and pub¬ 
lishing. Uploading is the process of putting the form template on the server, and publishing 
is the process of placing the form templates into sites on the content database so that users 
have access. 


Security 

As mentioned earlier, only server administrators can deploy form template solutions that con¬ 
tain code. Users who have either the Contributor or Web Designer role can create a form 
library based on form templates that do not contain code, as they could in previous versions 
of Windows SharePoint Services. Users with these roles can also create a form library with 
domain-based form templates that contain code or fully trusted form templates that contain 
code, but these form templates will work only in Office InfoPath 2007. 

Here are some other considerations about security when using Office Forms Server 2007: 

■ Office Forms Server 2007 relies on the Windows SharePoint Services 3.0 AppDomain to 
load and run business logic code. 

■ Office Forms Server 2007 supports only domain-based and fully trusted solutions. 

■ Office InfoPath 2007 form templates will get the ASP.NET/Medium permission set 
as defined in the WSS_MediumTrust policy file. Office Forms Server 2007 uses 
PermissionDeny to remove the permissions that are defined in the Domain_new secu¬ 
rity profile. 

■ Cross-domain access is not allowed on Office Forms Server 2007. The form template 
receives a security exception when it crosses domain boundaries. In contrast, on the 
Office InfoPath 2007 client a user is prompted, which is the same behavior as in 
InfoPath 2003. This difference creates scenarios in which the form template does not 
work on the server but does run on the client. 


Custom ASP.NET Pages with the InfoPath Form 
Services Control 

Office Forms Server 2007 includes a control, named XmlFormView, in the Microsoft.Office.Info- 
Path.Server.Controls namespace. (You’ll see an example that uses this control later in the 
chapter.) Developers can use the XmlFormView control to host Office InfoPath 2007 form 
templates in a custom ASP.NET page. Hosting the control allows you to manage the appear¬ 
ance of the Web page and provides Web-based form templates for users to fill out. The 
XmlFormView control includes various properties, methods, and events that allow program¬ 
matic access to operations such as initializing and closing the form template and a “submit 
to host” mechanism that can be used to send an event to the parent process, such as the 
.aspx page. 
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Some of the limitations of working with the XmlFormView control include the following: 

■ Only one XmlFormView control can be used per page. 

■ Development in Visual Studio must occur on the same machine on which Office Forms 
Server 2007 is installed. 

■ The client-detection logic available on standard Web-enabled form templates will not 
work on custom pages hosting the control. 

Automating Office Forms Server 2007 
Administration Tasks 

The Office Forms Server 2007 object model allows an administrator to automate tasks 
through the use of the .NET Framework. Many of these tasks can be managed through 
command-line switches run with Stsadmin.exe as well. 

The main objects in the Microsoft.Office.InfoPath.Server.Administration namespace include the 
following: 

FormsService class The highest level of the forms server topology represents Office Forms 
Server 2007 Server Administration on the Web farm. The FormsService class extends 
Microsoft. SharePoint.Administration.SPService. 



Note Windows SharePoint Services defines SPService as a farm-wide application or the base 
object for any root "controller'' object for a server application. 


Here is an example of retrieving and using the FormsService class: 

SPFarm farm = SPFarm.Local; 

FormsService ser = farm.Services.Getva1ue<FormsService>(""); 
Consoie.writeLine(ser.FormTempiates.Count); 

The following table lists the properties of the FormsService class: 


Property 

Description 

Instances 

An SPServIcelnstanceCollectlon inherited from SPService. A 
collection of FormsServicelnstances, where there is one Forms- 
Servlcelnstance per SPServer on the SPFarm. 

FormTempiates 

A FormTemplateCollection, an enumeration containing all of the 
FormTemplate objects registered on the farm. 

DataDefaultConnectionTImeout 

Returns an int representing the default data connection time¬ 
out in milliseconds. 

DataMaxConnectionTimeout 

Returns an int representing the maximum data connection time¬ 
out in milliseconds. 
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FormTemplate class The FormTemplate class represents an Office InfoPath 2007 form tem¬ 
plate or an .xsn file that has been deployed to the forms server. All FormTemplate classes on 
the server are contained in FormTemplateCollection on the FormsServerService class. The follow¬ 
ing tables list the methods and properties of the FormTemplate class. 


Method 

Description 

Activate{SPSite site) 

Activates or reactivates a previously uploaded form template 
to the site specified by site. Fails if the form template is 
deployed by using RegisterFormTemplate. 

Deactivate(SPSite site) 

Inverse operation of Activate. Fails if a form template is 
deployed by using RegisterFormTemplate. 

GetAbsoluteUrl(SPSite site) 

Returns the absolute URL of the form template at the given 
site in the current user context. 

QuiescefTimeSpan maxDuration) 

Starts quiescing the form template for the time specified by 
maxDuration. 

QuiesceEndTImef) 

Returns the time the form template will stop quiescing as a 
System. DateTime. 

UnquiesceQ 

Stops quiescing the form template. 


Property 

Description 

Category 

Gets or sets the category to which the FormTemplate is 
assigned. 

CreatedTimeUtc 

Gets the creation time as universal time (not local time). 

DataConnectionFileReferences 

Gets the collection of data connection file references. 

Description 

Gets the description attribute from the form template .xsf file. 

Featureld 

Gets the ID (GUID) of the feature ( SPFeatureDefinition ) that 
contains this FormTemplate. 

Formld 

Gets URN of the FormTemplate. 

Id 

Gets or sets the ID (GUID) of the FormTemplate in the Form¬ 
TemplateCollection object. Inherited from SPPersistedObject. 

IsFullTrust 

Gets a Yes/No string that specifies if the form template is 
full trust. 

IsSigned 

Gets a Yes/No string that specifies whether the form tem¬ 
plate is signed. 

Locale 

Gets a string that specifies the form template locale (for 
example, en-US). 

ModifiedTimeUtc 

Gets the last modified time as universal time (not local time). 

QuiesceState 

Gets the current quiesce state as a QuiesceMode enumera¬ 
tion: Normal, Quiesced, or Quiescing. 

Solutionld 

Gets the ID (GUID) of the solution that contains the XSN. 

ViewStateEnabled 

Gets or sets whether the form template is currently using 
view state. This property can only be set when the form tem¬ 
plate is quiesced. 
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Working with InfoPath Forms and Forms Server 

In the sections that follow, you’ll see examples of an InfoPath template that is used by our fic¬ 
titious Litware consultants to fill in daily time sheets. The template will be deployed so that 
consultants can use either the InfoPath client or a browser to enter time sheet data. Well also 
demonstrate the XmlFormView control and some other new ASP.NET and Windows controls 
that developers can use to embed an InfoPath form within an application. 

Creating an InfoPath Form to Capture Time Sheet Data 

To start this example, we will create two InfoPath template parts, which are form elements 
that can be saved and used in template after template. The first template part is for the Litware 
banner, and the second is a form footer that contains text that Litware uses on its internal 
documents. 

In InfoPath, in the Pill Out A Porm dialog box, click Design A Porm. In the Design A Form dia¬ 
log box, select the Template Part option and base the template part on a blank template. Also 
select the Web Browser Enabled option because this form template will be deployed to an 
Office Forms Server 2007 site later. Figure 9-2 shows the Design A Form dialog box with the 
options selected. 


Design a Form 


Open a form template 1 

Design a new: 

i.' j On My Computer,., 

C Form Template <• Template Part 

On a SharePoint Site... 1 

Design a template part that can be inserted and updated in multiple forms. 

frj Customize a Sample... 


Forms on Office Online ' 

Based on: 

Import... 

a la 

Recent form templates 

XML or Schema 

Time5heet_l 


SimpleTimeSheet 


TimeSheet 


Timesheet 


Create a form that allows you to define the data source while you are designing the 

Fill out a form ! 

Form. 

1 Fill Out a Form... 

W Web browser enabled 


OK | Cancel | 


Figure 9-2 The Design A Form dialog box. Note the Web Browser Enabled option. 


After the InfoPath design window opens, in the Design task pane, click Layout and then 
double-click the Two-Column Table option. In the table’s first cell, we enter the text Litware 
Inc, and in the second cell, the text Our code is so tasty, it will melt in your mouth. We can 
then apply some borders and shading to the table and formatting to the font. Figure 9-3 on the 
next page shows the template part up to this point. 


We add a second row to the table and merge this table’s cells. In the merged cell, we add the 
text Add here the title of the template, and then save the template part as Banner.xtp. 
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Figure 9-3 The initial appearance of the banner template part 

For the second template part, we follow the same initial steps, choose the One-Column Table 
option for the layout, and then add the text Litware Inc. Internal Document - All Rights 
Reserved. This template part is saved as Footer.xtp. 

We now have two reusable InfoPath blocks and can design an InfoPath template that will 
incorporate these template parts and be used to capture time sheet information. To begin the 
template, we need to take care of the layout and the controls, and then we can turn our atten¬ 
tion to linking the template to some data sources and adding its functionality. Figure 9-4 
shows the completed template in design view. Like the template parts, the form template was 
designed so that is it enabled for Web browsing. 

As mentioned earlier, InfoPath does not support all types of controls on a form that is enabled 
for Web browsing. When you click Controls in the Design task pane, InfoPath displays the 
controls that can be used, and a message box at the bottom of the task pane indicates that 
some controls are not compatible with server forms and have been hidden. Clicking the mes¬ 
sage in the task pane displays a message box, shown in Figure 9-5, that lists controls that 
aren’t compatible with server forms, including a combo box, file attachments, a multiple- 
selection list box, and others. 



Note During development of a form template, you can run the Design Checker to view and 
correct any compatibility errors with the selected run-time environments. Once you choose a 
form mode, you can switch the compatibility by using the Change Compatibility Settings link 
in the Design Checker task pane. 
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Figure 9-4 The time sheet form template in design view 


Microsoft Office InfoPath 


X] 


The following controls are not supported in server forms: 

- ComboBox 

- Multiple-Selection List Box 

- Master/Detail 

- Bulleted, Numbered and Plain List 

- Picture 

- Ink Picture 

- File Attachment 

- Vertical Label 

- Scrolling and Horizontal Region 

- Horizontal Repeating Table 

- Choice Group 

- Repeating Choice Group 

- Choice Section 

- Repeating Recursive Section 

- Custom Controls 


OK 


Figure 9-5 InfoPath displays the controls that are not 
compatible with a form that is enabled for Web browsing. 


To add the banner and the footer template parts to this form, first click the Add Or Remove 
Custom Controls link at the bottom of the pane. Add the template parts, and then you can 
drag the banner and the footer onto the blank form view. For this template, the text “Daily 
Timesheet Report Form” is added to the placeholder in the second row of the banner. 


Here’s a summary of the rest of the work required to lay out the form as it’s shown in 
Figure 9-4. Some additional borders and shading were applied to format the table. 


■ Using the Layouts task pane, we added a custom table with four columns and two rows. 
We added Consultant as the label in the first cell of row 1; Email in the first cell of row 
2; Date in the third cell of row 1; and Phone in the third cell of row 2 

■ Using the Controls task pane, we added the following controls to the view: 

□ A drop-down list box in the second cell of row 1, for consultants 
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□ A date picker in the fourth cell of row 1 

□ An expression box in the second cell of row 2 

□ An expression box in the fourth cell of row 2 

■ We added a repeating table to the form, with four columns. The column headers are 
Project, Task, Description, and Hours. The text box under Project was changed to a 
drop-down list box using the Change To command on the shortcut menu. 

We’ve built this form largely from scratch, but as we add controls to the form, InfoPath gener¬ 
ates an XSD schema. You can see the default names InfoPath assigns to the elements by click¬ 
ing on Data Source in the Design task pane. You can modify the schemas by changing the 
default names and types, for example. Using the Data Source task pane, we renamed the 
default elements as follows: 

■ myFields to timesheet 

■ myFields_l to banner 

■ myFields_2 to footer 

■ field 1 to consultant 

■ field2 to date 

■ group 1 to items 

■ group 2 to item 

■ field3 to project 

■ field4 to taskID. We also changed the type to Whole Number (integer) 

■ field5 to description 

■ field6 to hours. We also changed the type to Decimal (double) 

We continued building the form by adding a group under the timesheet element, called 
header, using the Move Up command to position the new group. We moved the consultant 
and date fields to the new group, and moved the banner and the footer elements to the bot¬ 
tom. Figure 9-6 shows the Data Source task pane after these changes have been made. 

We completed the form’s layout by right-clicking the table to open the Repeating Table Prop¬ 
erties dialog box. On the Display tab of the dialog box, we selected the Include Footer check 
box. Finally, we added an expression box control to the Hours column in the footer row, used 
the formula editor to insert a Sum function for the Hours field, and changed the type of the 
expression box content to Decimal. 

With the form template set up with controls and formatting, we can begin to take care of pop¬ 
ulating the drop-down list boxes with data. The first data connection we’ll create retrieves con¬ 
sultant data from a database (a simple Microsoft Access database in this example). The second 
data connection retrieves project data from a SharePoint list. 
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Figure 9-6 The Data Source task pane shows the names for the elements in the template. 

In InfoPath, we start by selecting Tools, Data Connections. Stepping through the series of 
screens, we specify first that this connection is for receiving data. Next we select Database, and 
then browse to the database file and select the Consultants table. We also choose to store the 
consultant’s data in the template to support offline scenarios. 

For the second data connection, we specify the URL to the SharePoint site where our Projects 
list is stored and then select the list by name. We included the fields named Code, Project 
Title, and Manager, and here as well, we select the option to store the project data in the tem¬ 
plate to support offline work. 

We associate the Consultant drop-down list box with the Consultants data connection by 
double-clicking the control, selecting Look-Up Values From An External Data Source, and 
specifying Consultants as the data connection. We also specify the Name field as the field to 
be displayed and stored in the XML that is generated from the data entered in the form. Like¬ 
wise, the Projects drop-down list is linked to the Projects data connection, with Code as the 
field that is displayed and stored. 

The next phase in creating the template is to add some validation and rules to the controls, 
which are set up in the properties dialog box for the control. Here are the rules and data vali¬ 
dation conditions that were added to the form: 

■ The Consultant field cannot be blank. 

■ Today’s date is set as the default date. 

■ Users are restricted from entering a date that is in the future. 
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■ The e-mail and phone fields are filled in automatically when a user selects a consultant. 
These lookups are performed by using XPath expressions such as the following: 

xdXDocument:GetDOMf"Consultants")/dfs:myFields/dfs:dataFields/d:Consultants/ 
@Telephone[. ./©Name = xdXDocument:get-DOMO/my:timesheet/my:header/my:consultant] 

■ Change the background color of the expression box that calculates the total of hours to 
red if the amount is higher than 8. 

As a last step, we add a button control to the form template that will be used to submit data to 
a Web service. Here’s the code for the ProcessSheet class that defines the SubmitTimesheet Web 
method that’s invoked through the Web service. 

using System; 

using System.xml; 

using System.web; 

using System.Collections; 

using System.web.Services; 

using System.web.Services.Protocols; 

using System.Data; 

using System.Data.OleDb; 

using System.10; 

/// <summary> 

/// Summary description for ProcessSheet 
/// </summary> 

[webService(Namespace = "http://www.litwareinc.com/")] 

[webServiceBinding(ConformsTo = wsiProfiles.BasicProfilel_l)] 
public class ProcessSheet : System.web.Services.webservice { 

[webMethod] 

public Boolean SubmitTimesheetfstring timesheet) 

{ 

//-- just for debugging 

Streamwriter sw = new Streamwriter(@”C:\data\temp.xml"); 
sw.write(timesheet); 
sw.CloseO; 

bool returnvalue = true; 


try 

{ 

StorelnDatabase(timesheet); 

} 

catch 


{ 

returnvalue = false; 

} 


} 


return returnvalue; 
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private void StorelnDatabase(string timesheet) 

{ 


//-- load the xml 

xml Document doc = new xmiDocument(); 
doc.Loadxmi(timesheet); 

//-- drop the timesheet items in the Access database 

string consultant = doc.SelectSingleNode(''//consultant") .innerText; 

DateTime date = Convert.ToDateTime(doc.SelectSingleNode("//date").InnerText); 

//-- grab the current data in the database 
OleDbConnection conn = new 

01eDbConnection(@"provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\Data\ 
Timesheet.mdb"); 
conn.Open(); 

OleDbCommand cmd = new Ol eDbCommandO; 
cmd.Connection = conn; 

//-- add the new stuff to it 

xmlNodeList items = doc.SelectNodes(”//item"); 

foreach (xmlNode item in items) 

{ 

cmd.CommandText = string.Format("lNSERT INTO TimeSheetData 

(Consultant,Project,ltemDate,TasklD,Description,Hours) " + 

" values('{ 0}','{1}','{2}', {3},'{4}',{5})", consultant, 
item.FirstchiId.InnerText, date, item.ChildNodesfl].InnerText, 
item.ChildNodes[2].InnerText,item.ChildNodes[3].InnerText); 
cmd. ExecuteNonQueryO; 

} 

//-- clean up 
conn.Close(); 


} 

We need to define a data connection for this Web service as well, although this connection is 
to submit data. After selecting Web Service as the type of connection, enter the URL to the 
Web service (http://localhost:6154/TimeSheetServices/ProcessSheet.asmx, for example—the 
port number will vary). Select the SubmitTimesheet method, and then select the timesheet field 
as the value for the input argument. Select XML Subtree, including the selected element, as 
the value for the Include option. 

With the data connection set up, we can create a rule that defines the button’s behavior. 
Double-clicking the button opens the Button Properties dialog box. The rule we define has no 
conditions but performs the following three actions: 

■ Submits the data using the Web service data connection 

■ Shows a dialog box with a thank-you message 

■ Closes the form 



200 


7 Development Projects for Microsoft Office SharePoint Server 2007 and Windows SharePoint Services 


The template is now ready to use. We can test the template by opening the form, entering 
some data, and then clicking the Submit button. If we get the message, the information was 
processed successfully by the Web service. 

Publishing a Form to a Windows SharePoint Services Forms Library 

In this section, we take on the role of an administrator responsible for deploying an InfoPath 
template. Well show how to deploy a template to a SharePoint forms library and make it avail¬ 
able through Office Forms Server 2007 for consultants who do not have InfoPath installed on 
their computers. 

Before deploying a template, you have to verify the security level. For the deployment to 
behave properly, follow these steps to request full trust, using settings on the Security And 
Trust page of the Form Options dialog box: 

■ Clear the check box for Automatically Determine Security Level Based On Form’s 
Design. 

■ Select the Full Trust option. 

■ Select Sign This Form, and then click the Create Certificate button. 

■ Select the Administrator certificate. 

In the Design task pane, click Design Checker to ensure that the form is compatible with 
being enabled for Web browsing. You should not see any red icons indicating a compatibility 
error. You might see one or more blue icons indicating a warning. 

Now click Publish Form Template in the Design task pane. A wizard guides you through the 
steps to publish the template to a SharePoint site or an Office Forms Server 2007 site. You 
need to specify the URL to the SharePoint server, and then you will create a document library 
for the form template. 

As an administrator of the forms library, you can specify that the InfoPath form always has to 
be filled in using the browser, even if a user has InfoPath installed on his or her computer, by 
setting the Opening Documents option mentioned earlier. 

Figure 9-7 shows the time sheet form open in the browser after being successfully published 
to Office Forms Server 2007. 
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Figure 9-7 The time sheet form rendered in the browser 

Embedding an InfoPath Form in an Application 

Developers now have the option to embed InfoPath forms within an application. You can 
work with two types of controls, one that you can use within ASP.NET applications, and the 
other with Windows applications. In this section, we’ll take a look at how to work with an 
embedded InfoPath control. In the first example, well show a Web page that displays a list of 
submitted time sheets. When a user selects a time sheet in the list, a control provides a read¬ 
only preview of the time sheet on the page itself. 

To host the Web application well work with, we created a virtual directory under the default 
Web site. The settings for virtual directory permissions included Run Scripts as well as the 
default options. The other setting we made on the Virtual Directories tab was to select Scripts 
Only for the Execute Permissions option. 

We also turned on session state for Office Forms Server 2007 by opening the Web.config file 
found at C:\inetpub\wwwroot and removing the comment markup from the SessionState 
entry in the HttpModule element, which is shown here: 

<add name="Session" type="System.web.Sessionstate.SessionStateModuie"/> 

Then we set enableSessionState to True in the pages element in the Web.config file: 

<pages enableSessionState="true" enabieviewState="true" 

enabieviewStateMac="true" vatidateRequest="faise" pageParserFi1terType= 

"Microsoft.Sharepoint.AppiicationRuntime.SPPageParse rFiiter, 

Microsoft.Sharepoint, version=12.0.0.0, Cu1ture=neutrai, 

PubiicKeyToken=71e9bcellle9429c" asyncTimeout="7"> 


We next created a new Web site application in Visual Studio 2005, setting the type to HTTP 
and choosing C# as the language. 
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In the designer, we add Litware Timesheet Viewer as the title of Default.aspx, and then add 
a table with two rows and two columns. In the first cell of the first row, we enter Timesheets, 
and then add a list box control to the second row. We named this control listTimesheets and 
set the AutoPostBack property to True. 

The next step is to right-click in the toolbox, and select Choose Items. Once the Choose Tool¬ 
box Items dialog box appears, use the Browse button to load Microsoft.Office.Info- 
Path. Server, dll from the C:\Program Files\Microsoft Office Server\12.0\Bin folder. Three 
controls are added to the list, including the XmlFormView control. 

We can now drop the XmlFormView control onto the second cell of the second row of the 
table. In the properties window, we change the name of the control to xmlFonnViewTimesheets 
and set the Visible property to False. Figure 9-8 shows a preview of the form in the browser. 
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Figure 9-8 An example of the XmlFormView control 

We next add the code to display all the submitted time sheets in the http://ossl/Daily 
Timesheets forms library. In the code-behind file for Default.aspx, we need to add a reference 
to Microsoft.SharePoint.dll and then declare the namespace: 

using Microsoft.SharePoint; 

Next we create a private procedure that will encapsulate the code that populates the list box. 
private void PopuiateListBoxO {} 

In this procedure, the code we write first establishes a connection to the forms library: 

SPSite site = new SPSite("http://ossl"); 

SPWeb web = site.Rootweb; 

SPList list = web.Lists["Daiiy Timesheets"]; 


The next step is to get the time sheet items as a DataTable type so that we can bind the data to 
the listTimesheets control. 
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DataTable timesheets = 1 ist.Items.GetDataTableO ; 

1istTimesheets.DataTextField = "Title"; 

1istTimesheets.DatavalueField = "ID"; 

1istTimesheets.DataSource = timesheets; 

1istTimesheets.DataBind(); 

Now we call this procedure in the Page_Load event handler: 

protected void Page_Load(object sender, EventArgs e) 

{ 

if(!Page.isPostBack) 

PopulateListBoxO ; 

} 

Figure 9-9 shows the populated list box when we view the page in the browser. 



Figure 9-9 The list box populated from the items in the forms library in SharePoint 

We now add the code that runs when a user selects a time sheet in the list box. The code ren¬ 
ders a read-only view of the time sheet on the form itself in the InfoPath control. To create this 
view, we handle the SelectedlndexChanged event of the listTimesheets control. Not a lot of code 
is required here. We just grab the selected item and pass it to the xmlFormViewTimesheets 
control: 

protected void listTimesheets_SelectedlndexChanged(object sender, EventArgs e) 

{ 

string selForm = listTimesheets.Selectedltem.Text; 

xmlFormviewTimesheets.xmlLocation = "http://°ssl/Daily Timesheets/" + selForm; 
xmlFormviewTimesheets.visibl e = true; 

} 

Figure 9-10 on the next page again shows the application previewed in the browser. 
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Figure 9-10 A preview of a specific time sheet is rendered in the XmlFormView control 

Now we’ll turn our attention to a Windows application that hosts an InfoPath control that the 
user can use to fill in a new time sheet report. The application provides assistance to the user 
by means of a panel that displays project information. We’ll use a Visual Studio 2005 Win¬ 
dows application named TimeSheetWinApp. 

After creating the application, we right-click in the toolbox and select Choose Items. In the 
Choose Toolbox Items dialog box, in the .NET components list, we select the item for the 
form control that is associated with the Microsoft.Office.InfoPath namespace. (If this control 
is not available, it can be added by browsing to C:\Program Files\Microsoft Office\ 

Micro soft.Office.Info Path.dll.) 

We drop the form control on the design surface of forml, change the name to formControl- 
Timesheet and set the Dock property to Left. Then we add a splitter control and a panel control 
to the form as well. For the panel control, we set the Dock property to Fill. 

Using the New Data Source Wizard in Visual Studio, we create a data source to an Office 
Access 2007 database that contains one table, named ProjectTasks, with a number of task 
items per project. 

We drag the ProjectTasks fields from the Data Source pane to the panel on the form, and then 
add two buttons to the panel: buttonlnsert with its Text property set to Insert, and buttonSave 
with its Text property set to Save. 

The first coding task is to display the InfoPath form to be filled out in the control. In the con¬ 
structor, we add the following line after the call to InitializeComponent: 

formControiTimesheet.NewFromSoiution("http://oss1/Daiiy%20Timesheets/Forms/tempiate.xsn"); 
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We can now run the application again and see the time sheet form to be filled in, shown in 
Figure 9-11. 
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Figure 9-11 A Windows application that hosts an InfoPath form 


Return to the designer after closing the application and double-click the Save button. The con¬ 
trol only allows the form to be saved to an absolute path. To handle this, we first need to add 
a couple of namespace declarations to the code: 


using Microsoft.Office.InfoPath; 
using System.xmi; 
using System.xmi.XPath; 

We construct the name of the file that we will save by concatenating the values for the consult¬ 
ant and the date. The form control exposes an XMLForm that provides you with an entry point 
to the XML that is stored in the form. You can access the XML through the MainDataSource 
property. From then on it is a matter of parsing the XML to construct the file name. 

XPathNavigator nav = 

formControlTimesheet.xml Form.MainDataSource.CreateNavi gator().SelectSingleNode 
(”/my:timesheet/my:header/my:consultant", 
formControlTimesheet.xml Form.NamespaceManager); 
string file = @"C:\Ascend\Labs\08_lnfoPath\Lab\Timesheets\"; 
file += nav.value + 

nav.MoveToNext(XPathNodeType.Element); 
file += nav.value.ReplaceC"-", + ".xml"; 

MessageBox.Show(fi1e); 

The purpose of the Insert button is to create a new item in the repeating table using the project 
and task displayed in the panel. To provide this functionality we will handle the Click event of 
the button. 

If a user has not yet added any time sheet items, you can populate the row that already exists, 
which means you need to check, for example, whether the project field of the first item in the 
repeating table is empty. 
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XPathNavigator nav = 

formControlTimesheet.xml Form.MainDataSource.CreateNavigator().SelectSingleNode 
(”/my:timesheet/my:items/my:item[1]/my:project", 
formControlTimesheet.xml Form.NamespaceManager); 
if (nav.value == string.Empty) { 

} 

el se { 

} 

If this item is the first element in the repeating table, then we can set the values of the different 
columns of the item. 

nav.Setvalue(projectTextBox.Text); 
nav.MoveToNext(XPathNodeType.Element); 
nav.Setvalue(tasklDTextBox.Text); 
nav.MoveToNext(XPathNodeType.Element); 
nav.Setvalue(descriptionTextBox.Text); 

If this is not the first item, we need to create a row in the repeating table, and then make sure 
that we have access to the last row element added so that we can modify those values. 

formControlTimesheet .xml Form.Currentview. ExecuteAction(ActionType.xCollectiomnsert, 
"group8_7"); 

XPathNavigator newNav = 

formControlTimesheet.xml Form.MainDataSource.CreateNavigator().SelectSingleNode 
(”/my:timesheet/my:items/my:item[last()]/my:project", 
formControlTimesheet.xml Form.NamespaceManager); 
newNav.Setvalue(projectTextBox.Text); 
newNav.MoveToNext(XPathNodeType.Element); 
newNav.Setvalue(tasklDTextBox.Text); 
newNav.MoveToNext(XPathNodeType.Element); 
newNav.Setvalue(descriptionTextBox.Text); 



